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:

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:

Post Body Example:

{
  "account": {
    "id": 25601,
    "externalAccountId": null
  },
  "yourPhoneNumber": {
    "id": 311903,
    "externalPhoneId": null,
    "description": "Main office",
    "phoneNumber": "14234368617"
  },
  "conversation": {
    "id": 7469828,
    "date": "2019-09-03T15:45:15.3812028Z",
    "consumerPhoneNumber": "14236845309",
    "messageDirection": "S",
    "message": "This is a sent message.",
    "status": null,
    "claimedBy": null,
    "consumerFriendlyName": "Peter Parker"
  }
}

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:

Post Body Example:

{
  "account": {
    "id": 25601,
    "externalAccountId": null
  },
  "yourPhoneNumber": {
    "id": 311903,
    "externalPhoneId": null,
    "description": "Main office",
    "phoneNumber": "14234368617"
  },
  "conversation": {
    "id": 7469828,
    "date": "2019-09-03T15:45:15.3812028Z",
    "consumerPhoneNumber": "14236679106",
    "messageDirection": "R",
    "message": "This is an inbound message.",
    "status": null,
    "claimedBy": null,
    "consumerFriendlyName": "423-667-9106"
  }
}

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:

Post Body Example:

{
  "ContactId": 7475624,
  "LocationPhoneNumber": "14234368617",
  "ContactPhoneNumber": "15044870012",
  "ContactFriendlyName": "Steven Tyler"
}

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.