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 Authorization header to the value Bearer <token>, replacing <token> with the API access token belonging to your organization.
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:

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

{
   "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": "Sent",
   "direction": "outbound",
   "message_type": "SMS",
   "segment_count": 2,
   "error_code": "000",
   "error_message": "Details on error",
   "mno_name": "Regional Name of Phone Carrier",
   "message_size_bytes": 15,
   "message_created_at": "2024-04-24T00:00:00",
   "messaging_profile_id": "Sub-Account-Prover-Assigned-Id",
   "messaging_profile_name": "Specific Profile/Sub Account Label"
}

Responses

Example Successful message received

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

Example Error message

Token not provided, see request setup

{
    "message": "Unauthorized: token not provided",
    "requestId": "00000-22222-44444-55555-66666"
}

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.

{
    "message": "Unauthorized: token was deleted",
    "requestId": "112a641c-8ea7-48d0-a1a2-e86ca0646352"
}

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

{
    "statusCode": 400,
    "body": {
              "message": "Bad Request: check that required parameters are provided in the request",
              "requestId": "ex-am-pl-id-12-34"
          }
}

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.

Volt GraphQL API Guides

Sending Message Details to Volt Insights API

Analytics