Messaging
Send SMS
IMPORTANT: 10DLC Compliance must be considered when sending messages to multiple numbers or sending multiple programmatic requests. Messages are subject to rate limits determined by your brand and messaging campaigns tier. Exceeding rate limits will result in messaging failures.
Post Parameters
- Name
tenantId*
- Type
- number
- Description
- Account id
- Name
from*
- Type
- string
- Description
10DLC number from which to send the message. This number must belong to your account, be assigned as an extension SMS destination, and be provisioned in the 10DLC ecosystem
- Name
to*
- Type
- string[]
- Description
- Array of phone numbers to send the message to
- Name
text*
- Type
- string
- Description
- The message body
Header
- Name
Authorization*
- Type
- string
- Description
Bearer
{accessToken}
- Name
Content-Type*
- Type
- string
- Description
- application/json
Request
curl --location -g --request POST 'https://api.voxo.co/v2/messaging/sendSMS' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}'
Response
{
"tenantId": 1234,
"from": "6015555555",
"to": ["6015555556", "6015555557"],
"text": "Hot dad riding in on a rhino"
},
Upload Media Files
Header
- Name
Authorization*
- Type
- string
- Description
Bearer
{accessToken}
- Name
Content-Type*
- Type
- string
- Description
- multipart/form-data
Request
curl --location -g --request POST 'https://api.voxo.co/v2/messaging/uploadMediaFiles' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer {accessToken}'
Response
[ "https://voxo-mms.s3.amazonaws.com/UGQ1USBXAZN1AKA3.png" ]
Send MMS
IMPORTANT: This will not send an individual MMS to each recipient in the array. This will create a group thread with the source number and all of the recipients.
Post Parameters
- Name
tenantId*
- Type
- number
- Description
- Account id
- Name
from*
- Type
- string
- Description
10DLC number from which to send the message. This number must belong to your account, be assigned as an extension SMS destination, and be provisioned in the 10DLC ecosystem
- Name
to*
- Type
- string[]
- Description
- Array of phone numbers to send the message to
- Name
text
- Type
- string
- Description
- The message body
- Name
mediaUrls
- Type
- string[]
- Description
- The array of public urls
Header
- Name
Authorization*
- Type
- string
- Description
Bearer
{accessToken}
- Name
Content-Type*
- Type
- string
- Description
- application/json
Request
curl --location -g --request POST 'https://api.voxo.co/v2/messaging/sendMMS' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}'
Response
{
"createdConversations": [
{
"id": 945,
"tenantId": 37,
"createdAt": "2023-08-22T16:20:55.000Z",
"updatedAt": "2023-08-22T16:20:55.000Z",
"sourceDID": "16015555556",
"participants": "16015555557,16015555556,16015555555",
"hidden": 0,
"name": "VOXO,16015555555",
"conversationName": ""
}
],
"id": 4843,
"postBody": {
"tenantId": 37,
"from": "6015555556",
"to": [
"6015555555",
"6015555557"
],
"text": "Hello",
"mediaUrls": [
"https://voxo-mms.s3.amazonaws.com/TTMGNJNYASY0UGJM.jpeg"
]
},
"updatedAt": "2023-08-22 11:20:59"
}
Get SMS Provisioned Numbers
This will return all of your numbers provisioned for SMS and the status for if they are active in a campaign.
Header
- Name
Authorization*
- Type
- string
- Description
Bearer
{accessToken}
- Name
Content-Type*
- Type
- string
- Description
- application/json
Request
curl --location -g --request GET 'https://api.voxo.co/v2/messaging/getProvisionedNumbers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}'
Response
[
{
"tn": "6015555556",
"active": 1
}
]
Hide Conversation
IMPORTANT: This does not delete the existing thread. The conversation is just marked as hidden in the database.
Post Parameters
- Name
conversationId*
- Type
- number
- Description
- Conversation Id
Header
- Name
Authorization*
- Type
- string
- Description
Bearer
{accessToken}
- Name
Content-Type*
- Type
- string
- Description
- application/json
Request
curl --location -g --request POST 'https://api.voxo.co/v2/messaging/deleteConversation' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}'
Response
{
"conversationId": 153
}
Update Conversation Name
IMPORTANT: This endpoint will only modify the name for your conversation. Other participants will never see the name change.
Post Parameters
- Name
conversationId*
- Type
- number
- Description
- Conversation id
- Name
conversationName*
- Type
- string
- Description
- New conversation name
Header
- Name
Authorization*
- Type
- string
- Description
Bearer
{accessToken}
- Name
Content-Type*
- Type
- string
- Description
- application/json
Request
curl --location -g --request POST 'https://api.voxo.co/v2/messaging/updateConversationName' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}'
Response
{
"conversationId": 153,
"conversationName": "Friends"
}
Mark Read
IMPORTANT: This will mark the conversation as unhidden (if it is hidden) and mark all of the messages associated with the thread as read.
Post Parameters
- Name
conversationId*
- Type
- number
- Description
- Conversation id
Header
- Name
Authorization*
- Type
- string
- Description
Bearer
{accessToken}
- Name
Content-Type*
- Type
- string
- Description
- application/json
Request
curl --location -g --request POST 'https://api.voxo.co/v2/messaging/markRead' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}'
Response
{
"conversationId": 153,
}
List conversations
Returns a complete list of a user's text message threads
Parameters
- Name
userId*
- Type
- number
- Description
- User id
Header
- Name
Authorization*
- Type
- string
- Description
Bearer
{accessToken}
- Name
Content-Type*
- Type
- string
- Description
- application/json
Request
curl --location -g --request GET 'https://api.voxo.co/v2/messaging/listConversations/1234' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}'
Response
[
{
"id": 3,
"createdAt": "2023-06-29 21:51:24",
"updatedAt": "2023-08-22 12:14:00",
"sourceDID": "16015555556",
"participants": "16015555557,16015555556,16015555558",
"tenantId": 37,
"hidden": 0,
"name": "VOXO,VOXO,VOXO",
"conversationName": "Team",
"unreadCount": null,
"lastMessage": "Hello Team!",
"lastMessageId": 4779,
"lastMedia": []
}
]
Get messages
Note: This is a paginated endpoint
Parameters
- Name
userId*
- Type
- number
- Description
- User id
- Name
conversationId*
- Type
- number
- Description
- Conversation id
- Name
page
- Type
- number
- Description
- Page of the list
- Name
recordsPerPage
- Type
- number
- Description
- Number of results returned per page
Header
- Name
Authorization*
- Type
- string
- Description
Bearer
{accessToken}
- Name
Content-Type*
- Type
- string
- Description
- application/json
Request
curl --location -g --request GET 'https://api.voxo.co/v2/messaging/getMessages?userId=123&conversationId=123&page=1&recordsPerPage=100' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}'
Response
{
"messages": [
{
"id": 4779,
"userId": 123,
"conversationId": 123,
"text": "Hello",
"mediaUrls": [],
"to": "16015555556",
"from": "16015555557",
"direction": "inbound",
"timestamp": "2023-07-14T17:45:44.000Z",
"read": 0
},
{
"id": 4660,
"userId": 123,
"conversationId": 123,
"text": "Goodbye",
"mediaUrls": [],
"to": "16015555556",
"from": "16015555557",
"direction": "inbound",
"timestamp": "2023-07-14T14:48:38.000Z",
"read": 0
}
],
"totalMessages": 39,
"page": 1,
"recordsPerPage": 2
}
Search conversations
Parameters
- Name
number*
- Type
- number
- Description
- Phone number being queried
Header
- Name
Authorization*
- Type
- string
- Description
Bearer
{accessToken}
- Name
Content-Type*
- Type
- string
- Description
- application/json
Request
curl --location -g --request GET 'https://api.voxo.co/v2/messaging/getMessages?userId=123&conversationId=123&page=1&recordsPerPage=100' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}'
Response
[
{
"id": 209,
"tenantId": 37,
"createdAt": "2023-07-04T00:37:04.000Z",
"updatedAt": "2023-07-04T00:37:09.000Z",
"sourceDID": "16015555556",
"participants": "16015555556,16015555558,16015555555",
"hidden": 1,
"name": "VOXO,16015555555",
"conversationName": "VOXO, VOXO"
},
{
"id": 210,
"tenantId": 37,
"createdAt": "2023-07-04T00:37:09.000Z",
"updatedAt": "2023-07-06T17:58:31.000Z",
"sourceDID": "16015555558",
"participants": "16015555556,16015555558,16015555555",
"hidden": 0,
"name": "VOXO,16015555555",
"conversationName": "VOXO, 6015555555"
}
]