Got questions? Text us at 423-218-0111
Queuniversity

How to Use Text Request Webhooks for App-to-App Notifications

Last updated on

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:

  1. Program an endpoint to handle the webhook callback.
  2. 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:

  1. Message Sent
  2. Message Received, and
  3. Contact Created

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:

  1. Login to your Text Request account as an administrator. (Only administrators can register webhook handlers.)
  2. On the left-hand navigation menu, select the Integrations menu option.
  3. On the Integrations page, click the “API Key & WebHooks” link on the API card.
  4. Scroll to the bottom of the page to the Webhooks card to register your webhook.
  5. Choose your Event (Message Sent, Message Received, or Message Created).
  6. Choose your Verb (POST).
  7. Paste the URL for your handler into the Uri field.
  8. Click the Create button.

Your new webhook will be added to the system, and will start receiving calls from Text Request.

Text Request Webhooks