Sending Twilio Message Webhooks to Volt Insights API

Owned by Cody Crow
Last updated: Feb 20, 2023 by Andy Kantola (Unlicensed)
6 min read

You can get Twilio messages added to your Insights Dashboard by passing through the webhook payloads sent from Twilio to your registered webhook handler. This is a step-by-step guide on how to send Twilio webhooks to our Volt webhook.

While messages from any provider can be sent to Volt Insights API using the provider-agnostic API endpoint, a Twilio-specific endpoint can be used to make integration more straightforward for Twilio messaging. Be sure to complete both steps A and B to ensure that complete messaging data is available within Volt.

 Instructions

Prep

  1. Have your Volt API access token readily available. If you have a Volt GraphQL API, you may use the same token.

  2. Ensure you can reach the endpoint by sending an empty body with your bearer token.

If you are unsure of where to locate your API token, contact api@textvolt.com.

 

Step A: Twilio Message API Response

When you send a message using the Twilio SDK, it returns a Message object matching the structure shown in the Appendix. This Message object can be serialized to JSON and sent to Volt Insights API using the Twilio-specific endpoint:

URL

  1. https://v1.insights.api.textvolt.com/data/messages/twilio

POST

  1. Set the Authorization header to the value Bearer <token>, replacing <token> with the API access token belonging to your organization.

  2. Send a POST request to https://v1.insights.api.textvolt.com/data/messages/twilio with the body sent as JSON.

For example, to send the above request using curl:

  1. curl --location --request POST https://v1.insights.api.textvolt.com/data/messages/twilio --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "api_version": "2010-04-01", "body": "McAvoy or Stewart? These timelines can get so confusing.", "date_created": "Thu, 30 Jul 2015 20:12:31 +0000", "date_sent": "Thu, 30 Jul 2015 20:12:33 +0000", "date_updated": "Thu, 30 Jul 2015 20:12:33 +0000", "direction": "outbound-api", "error_code": null, "error_message": null, "from": "+15017122661", "messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "num_media": "0", "num_segments": "1", "price": null, "price_unit": null, "sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "status": "sent", "subresource_uris": {"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"}, "to": "+15558675310", "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"}'

 

Request Body

Twilio Webhook Payload

Send the entire JSON-serialized Twilio Message object as the POST request body. Note that all fields are optional, but failure to include data may result in certain functionality being unavailable.

Responses

Example Successful message received

{ "statusCode": 202, "headers": {'Content-Type': 'application/json'}, "body": { "message": "Received message data", "requestId": "ex-am-pl-id-12-34" } }

 

Example Error message

Token not provided, see request setup

Token has been deleted and a new one has been generated or needs to be generated.

If you are unsure of where to locate your API token, contact api@textvolt.com.

Ensure that the required fields are being sent in the message body.

 

When processed, your message will be part of the data on the Insights Dashboard.

Step B: Status Callbacks

If you have configured a status callback URL when sending messages through Twilio, you will receive a status callback containing delivery status information. Use the data from that status callback to update your message data in Volt:

URL

Extract data from Twilio status callback

The Twilio-specific endpoint for Volt Insights API expects a JSON body with the structure shown below in the Appendix. You will need to extract these data points from the Twilio status callback:

  • SmsSid — map this to the sid field in the request body

  • MessageStatus — map this to status in the request body

  • ErrorCode — map this to error_code in the request body

Example

The values in the following example status callback body should be mapped to the values in the following example Insights API request body.

Example Twilio Status Callback
Example Insights API Request Body

POST

To send a message status update to the Insights API:

  1. Set the Authorization header to the value Bearer <token>, replacing <token> with the API access token belonging to your organization.

  2. Send a POST request to https://v1.insights.api.textvolt.com/data/messages/twilio with the body sent as JSON.

For example, to send the above request using curl:

Appendix: Expected JSON request body

The Twilio-specific Insights API endpoint expects a JSON object matching the structure of the Twilio Message object, which is returned when sending a message using the Twilio SDK.

 

 

next step…

Testing your Integration with Volt Insights

When you’re ready to test your integration with the Volt Insights UI, below are some important things to be aware of and some quick ways to test the data you’ve sent is present.

 

Verifying Data by Date:

When logging into your account and viewing the Dashboard page you may see a screen and message that says “No data to display for the date range selected.” Change the date range using the date picker above to when you expect data to be available.

This message is shows when the date in the date picker does not align with the created at time stamp for the test messages you’ve sent when setting up your integration. See Using Date Picker instructions below for more details.

 

Using Date Picker:

When selecting a date range in the date picker you should select a date range that corresponds with a required data field called “message_created_at”  that has been sent as part of the request body to the Volt Insights web-hook URL when completing the integration. This field is the date and time you sent the message to your provider, not the date and time you send the data to Volt. We use this timestamp to better correspond with the date and time your messages are sent each day and to help you more closely monitor delivery metrics as messages occurred.

 

Example of required field as described in Developer Documentation:

 

Additional Tip: Be sure to pay attention to the date and time selected in the date picker when choosing a range.

 

How to test for all data sent within a date range:

Make sure you know the specific “message_created_at” date and time range of all the messages you’ve sent as a test. Then select that date and time range in the date picker and hit the Refresh Dashboard button.

Next, use the Message Details & Logs card on the Dashboard to download the CSV file for Total Messages (In/Out). This should provide you with a spreadsheet of all messages to verify they are present with the correct “message_created_at” date as well as other fields of data. Other Graphs in the UI will also reflect the total volume of messages in and out. However this is the easiest way to ensure the data was received by Volt.

If any data is missing, please reach out to your contact on our engineering team for help our contact support at help@textvolt.com.