Sending Telnyx Message Webhooks to Volt Insights API

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

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

 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.

 

Telnyx Webhook Endpoint

URL

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

 

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/telnyx 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/telnyx --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{"event_type": "message.finalized", "id": "f310-6dea-4676-bf79-123456789012", "occurred_at": "2022-12-08T22:04:04.154+00:00", "payload": {"cc": [], "completed_at": "2022-12-08T22:04:04.154+00:00", "cost": {"amount": "0.0075", "currency": "USD"}, "direction": "outbound", "encoding": "GSM-7", "errors": [], "from": {"carrier": "Telnyx", "line_type": "Wireless", "phone_number": "+15555550123"}, "id": "403184f3-c45c-47a9-9db5-123456789012", "media": [], "messaging_profile_id": "40017ced-0e07-439d-88ff-123456789012", "organization_id": "1be7b732-8b26-4ae0-9634-123456789012", "parts": 1, "received_at": "2022-12-08T22:04:03.076+00:00", "record_type": "message", "sent_at": "2022-12-08T22:04:03.272+00:00", "tags": [], "text": "This is an example SMS body.", "to": [{"carrier": "CELLCO PARTNERSHIP DBA VERIZON WIRELESS - CA", "line_type": "Wireless", "phone_number": "+15555550124", "status": "delivered"}], "type": "SMS", "valid_until": "2022-12-08T23:04:03.076+00:00", "webhook_failover_url": "", "webhook_url": "https://example.com/webhook_endpoint"}, "record_type": "event"}'

 

Request Body

Telnyx Webhook Payload

Send the entire Telnyx webhook payload 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.

 

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.