How to Use Text Request Webhooks for App-to-App Notifications
Webhooks allow your applications to receive notifications when events take place in your Text Request account, like when new contacts are created or you get a new message.
Webhooks will require programmers to use (just send this page to your programmers and let them take care of things). If you do not have programming resources available, you can still make use of Text Request's webhooks by using our pre-built templates in Zapier.
Related: How to Integrate Text Request through Zapier
Currently, Text Request supports webhooks to alert you when a new message is sent, a new message is received, and a new contact is created.
Webhooks are defined at the Text Request dashboard level. A dashboard is a textable phone line inside your Text Request account. You can have multiple dashboards under one account, and each comes with its own set of users, contacts, settings, API key, and more.
Therefore, you can have different webhooks defined for your different Text Request dashboards. For example, a “message received” webhook for your sales dashboard might route to an endpoint that logs the new message in SalesForce, while a “message received” webhook for your support dashboard might route to an endpoint that opens a new support ticket in your CRM.
The steps involved in setting up a webhook are:
- Program an endpoint to handle the webhook callback.
- Register your endpoint with Text Request.
Let’s first look at each webhook’s definition, then see how to register an endpoint within Text Request.
Webhook Definitions
The three types of available Text Request webhooks are:
Message Sent Webhook
The Message Sent Webhook fires each time a new message is received for a Text Request dashboard.
HTTP Verb: POST
Content-Type: application/json
Post Body Definition:
|
Field |
Data type |
Description |
|
account.id |
number |
The Text Request unique identifier for your account. |
|
account.externalPhoneId |
string |
Used by partner accounts only. Holds the partner-specified identifier for this Text Request account. |
|
yourPhoneNumber.id |
The Text Request unique identifier for the dashboard that sent the message. |
|
|
yourPhoneNumber.externalPhoneId |
number |
Used by partner accounts only. Holds the partner-specified identifier for the dashboard that sent the message. |
|
yourPhoneNumber.description |
string |
The friendly name for the Text Request dashboard that sent this message. If a friendly name hasn’t been defined, this returns null. |
|
yourPhoneNumber.phoneNumber |
string |
The eleven digit Text Request dashboard phone number that sent the message. |
|
conversation.id |
number |
The Text Request unique identifier for the conversation between the sender and recipient phone numbers. |
|
conversation.date |
string |
The date and time that the message was sent. This is in ISO8601 format and in UTC time. |
|
conversation.consumerPhoneNumber |
string |
The eleven digit phone number for the message recipient. |
|
conversation.messageDirection |
string |
This will always be “S” for sent messages. |
|
conversation.message |
string |
The message that was sent. |
|
conversation.status |
string |
For partners only. This will be null for non-partner accounts. |
|
conversation.claimedBy |
string |
For partners only. This will be null for non-partner accounts. |
|
conversation.consumerFriendlyName |
string |
This will return the friendly name for the recipient if one has been set. If one has not been set, this will return the pretty-formatted recipient phone number. |
|
conversation.mmsAttachments |
array |
Holds an array of mmsAttachments. Each mmsAttachment will have the attachment's MIME type, and a URL where the attachment can be downloaded. If there are no MMS attachments for this message, this array will be empty. |
|
conversation.mmsAttachments.url |
string |
The URL where this attachment can be downloaded. |
|
conversation.mmsAttachments.mimeType |
string |
The MIME type for this attachment. |
Post Body Example:
Message Received Webhook
The Message Received webhook fires each time a new message is received for a Text Request dashboard.
HTTP Verb: POST
Content-Type: application/json
Post Body Definition:
|
Field |
Data type |
Description |
|
account.id |
number |
The Text Request unique identifier for your account. |
|
account.externalPhoneId |
string |
Used by partner accounts only. Holds the partner-specified identifier for this Text Request account. |
|
yourPhoneNumber.id |
The Text Request unique identifier for the dashboard that received the message. |
|
|
yourPhoneNumber.externalPhoneId |
number |
Used by partner accounts only. Holds the partner-specified identifier for the dashboard that received the message. |
|
yourPhoneNumber.description |
string |
The friendly name for the Text Request dashboard that received this message. If a friendly name hasn’t been defined, this returns null. |
|
yourPhoneNumber.phoneNumber |
string |
The eleven digit Text Request dashboard phone number that received the message. |
|
conversation.id |
number |
The Text Request unique identifier for the conversation between the sender and recipient phone numbers. |
|
conversation.date |
string |
The date and time that the message was received. This is in ISO8601 format and in UTC time. |
|
conversation.consumerPhoneNumber |
string |
The eleven digit phone number for the message sender. |
|
conversation.messageDirection |
string |
This will always be “R” for received messages. |
|
conversation.message |
string |
The message that was received. |
|
conversation.status |
string |
For partners only. This will be null for non-partner accounts. |
|
conversation.claimedBy |
string |
For partners only. This will be null for non-partner accounts. |
|
conversation.consumerFriendlyName |
string |
This will return the friendly name for the sender if one has been set. Otherwise returns the pretty-formatted sender phone number. |
|
conversation.mmsAttachments |
array |
Holds an array of mmsAttachments. Each mmsAttachment will have the attachment's MIME type, and a URL where the attachment can be downloaded. If there are no MMS attachments for this message, this array will be empty. |
|
conversation.mmsAttachments.url |
string |
The URL where this attachment can be downloaded. |
|
conversation.mmsAttachments.mimeType |
string |
The MIME type for this attachment. |
Post Body Example:
Contact Created Webhook
The Contact Created webhook fires whenever a new contact is created in a Text Request dashboard.
HTTP Verb: POST
Content-Type: application/json
Post Body Definition:
|
Field |
Data type |
Description |
|
ContactId |
number |
The Text Request unique identifier for the new contact. |
|
LocationPhoneNumber |
string |
The Text Request dashboard’s eleven digit phone number where this new contact was created. |
|
ContactPhoneNumber |
string |
The contact’s eleven digit phone number. |
|
ContactFriendlyName |
string |
The friendly name assigned to this contact. If no friendly name was specified, this property will be null. |
Post Body Example:
Test your webhook handler.
After creating your endpoint that will handle the Text Request webhook callback, we recommend testing your endpoint with a tool such as Postman. Using Postman, you can construct a HTTP request and ensure that your endpoint works as expected. Postman is free, simple to use, and can be downloaded from https://www.getpostman.com/products.
Register your Text Request webhook.
After creating and testing your webhook handler, it’s time to register your endpoint with Text Request. To register your endpoint, do the following:
- Login to your Text Request account as an administrator. (Only administrators can register webhook handlers.)
- On the left-hand navigation menu, select the Integrations menu option.
- On the Integrations page, click the “API Key & WebHooks” link on the API card.
- Scroll to the bottom of the page to the Webhooks card to register your webhook.
- Choose your Event (Message Sent, Message Received, or Message Created).
- Choose your Verb (POST).
- Paste the URL for your handler into the Uri field.
- Click the Create button.
Your new webhook will be added to the system, and will start receiving calls from Text Request.
