Sending Message Details to Volt Insights API
You can get messages added to your Insights Dashboard by passing along the message details and results from your provider’s webhook responses. This is a step-by-step guide to send message details to our Volt webhook.
Instructions
Prep
Have your Volt API access token readily available. If you have a Volt GraphQL API, you may use the same token.
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.
Messages Endpoint
URL
https://v1.insights.api.textvolt.com/data/messages
POST
Set the
Authorizationheader to the valueBearer <token>, replacing<token>with the API access token belonging to your organization.Send a
POSTrequest tohttps://v1.insights.api.textvolt.com/data/messageswith the body sent as JSON.
For example, to send the above request using curl:
curl --location --request POST https://v1.insights.api.textvolt.com/data/messages --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{"id": "ex-am-pl-id-12-34","provider": "telnyx","from_number": "+1234567890","to_number": "+1098765432","body": "The text you sent. Text STOP to Unsubscribe.","status": "delivered",message_created_at: "2024-04-24T00:00:00"}'
Request Body
Required Fields
Only id and provider are required, all other fields are nullable if you do not wish to send or if the field is not given from your provider.
Name | Type | Example | Description |
|---|---|---|---|
id | String |
| Unique message ID. You can use the id from provider |
provider | String |
| Name of the messaging provider used in lowercase Current known providers: twilio
bandwidth
telnyx
pinpoint
plivo
infobip
messagebird
commio
imimobile
sinch
vonage
smpp
ringcentral
cdyne |
message_created_at | String |
| Datetime the message was created by you in ISO 8601 format. If none is given, this will be the time the message is processed. |
message_sent_at | String |
| Datetime the message was sent (to or from the carrier) by your provider (CPaaS) in ISO 8601 format. If none is given, this will be the time the message is processed. |
message_finalized_at | String |
| Datetime the message was marked finalized by the provider (CPaaS) in ISO 8601 format. If none is given, this will be the time the message is processed. |
error_code | String |
| Code the provider returned if there was an issue with sending this message |
from_number | String |
| Phone number formatted in E.164 the message is being sent from |
to_number | String |
| Phone number formatted in E.164 the message was sent to |
body | String |
| Contents of the message sent |
status | String |
| Status returned from the provider |
direction | String |
| Direction of the message. Certain providers have more than inbound/outbound descriptions. These will be saved for future reference, but also normalized into inbound/outbound buckets |
message_type | String |
| Kind of message sent: SMS/MMS |
segment_count | Integer |
| Number of segments provider broke message into for sending |
Preferred Fields for Best Experience (not required)
If data is sent on an existing message previously sent to webhook, the field will be updated. Send Dates in ISO 8601 format, example '2024-03-14T13:00:00-05:00' (YYYY-MM-DDTHH:mm:ssZ).
Name | Type | Example | Description |
|---|---|---|---|
error_message | String |
| Details passed along from provider on error returned. |
mno_name | String |
| Mobile Network Operator name of the recipient phone number. May be the specific regional carrier used by recipient. |
message_profile_id | String |
| Sub account or messaging profile id given by the provider. |
messaging_profile_name | String |
| Name or label you have assigned given in the provider for a sub account or messaging profile. |
line_type | String |
| Indicates the type of number the to_number is such as “Wireless”, “Wireline”..etc |
Optional Fields
If data is sent on an existing message previously sent to webhook, the field will be updated. Send Dates in ISO 8601 format, example '2024-03-14T13:00:00-05:00' (YYYY-MM-DDTHH:mm:ssZ).
Name | Type | Example | Description |
|---|---|---|---|
provider_account_id | String |
| Your account or organization ID with Provider. |
message_size_bytes | Integer | 15 | Storage size of the message in bytes |
rate_amount | String |
| Rate per segment to send message through provider. |
rate_currency | String |
| Currency of the rate per segment. |
price_amount | String |
| Total cost to send message through provider. |
price_currency | String |
| Currency of the total cost. |
mcc | String |
| Mobile country code of the receiving number. |
mnc | String |
| Mobile network code of the receiving number. |
campaign_class | String |
| Message class of campaign per 10DLC from AT&T |
Example
Responses
Example Successful message received
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.