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

  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.

 

Messages Endpoint

URL

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

 

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 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 --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

Name

Type

Example

Description

id

String

"id": "ex-am-pl-id-12-34"

Unique message ID. You can use the id from provider

provider

String

"provider": "telnyx"

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 tychron

message_created_at

String

"2024-03-14T13:00:00-05:00"

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

"2024-03-14T13:00:00-05:00"

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

"2024-03-14T13:00:00-05:00"

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

"000"

Code the provider returned if there was an issue with sending this message

from_number

String

"+1234567890"

Phone number formatted in E.164 the message is being sent from

to_number

String

"+1098765432"

Phone number formatted in E.164 the message was sent to

body

String

"The text you sent. Text STOP to Unsubscribe."

Contents of the message sent

status

String

"delivered"

Status returned from the provider

direction

String

"outbound"

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

"SMS"

Kind of message sent: SMS/MMS

segment_count

Integer

2

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

Name

Type

Example

Description

error_message

String

"The destination phone number was deemed invalid by the carrier."

Details passed along from provider on error returned.

mno_name

String

"T-MOBILE USA, INC."

Mobile Network Operator name of the recipient phone number. May be the specific regional carrier used by recipient.

message_profile_id

String

"Sub-Account-Id-123"

Sub account or messaging profile id given by the provider.

messaging_profile_name

String

"Specific Sub Label"

Name or label you have assigned given in the provider for a sub account or messaging profile.

line_type

String

"Wireless"

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

Name

Type

Example

Description

provider_account_id

String

"id": "ex-am-pl-id-12-34"

Your account or organization ID with Provider.

message_size_bytes

Integer

15

Storage size of the message in bytes

rate_amount

String

"0.005"

Rate per segment to send message through provider.

rate_currency

String

"USD"

Currency of the rate per segment.

price_amount

String

"0.01"

Total cost to send message through provider.

price_currency

String

"USD"

Currency of the total cost.

mcc

String

"310"

Mobile country code of the receiving number.

mnc

String

"160"

Mobile network code of the receiving number.

campaign_class

String

"K"

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.

 

 Related articles