Messaging

POSThttps://api.voxo.co/v2/messaging/messages/send-sms

Send SMS

Send an SMS text message to one or more numbers

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

POST

/messaging/messaging/messages/send-sms

curl --location -g --request POST 'https://api.voxo.co/v2/messaging/messages/send-sms' \
--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"
},

POSThttps://api.voxo.co/v2/messaging/messages/upload-media

Upload Media Files

Upload files to receive a media url for MMS file attachments

Header

Name
Authorization*
Type
string
Description
Bearer {accessToken}
Name
Content-Type*
Type
string
Description
multipart/form-data

Request

POST

/messaging/messages/upload-media

curl --location -g --request POST 'https://api.voxo.co/v2/messaging/messages/upload-media' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer {accessToken}'

Response

[ "https://voxo-mms.s3.amazonaws.com/UGQ1USBXAZN1AKA3.png" ]

POSThttps://api.voxo.co/v2/messaging/messages/send-mms

Send MMS

Send an MMS text message to one or more numbers

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

POST

/messaging/messages/send-mms

curl --location -g --request POST 'https://api.voxo.co/v2/messaging/messages/send-mms' \
--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"
}

GEThttps://api.voxo.co/v2/messaging/get-provisioned-numbers

Get SMS Provisioned Numbers

Retrieve all of your numbers provisioned for SMS

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

GET

/messaging/get-provisioned-numbers

curl --location -g --request GET 'https://api.voxo.co/v2/messaging/get-provisioned-numbers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}'

Response

[
  {
    "tn": "6015555556",
    "active": 1
  }
]

DELETEhttps://api.voxo.co/v2/messaging/conversations/:id

Hide Conversation

IMPORTANT: This does not delete the existing thread. The conversation is just marked as hidden in the database.

Header

Name
Authorization*
Type
string
Description
Bearer {accessToken}
Name
Content-Type*
Type
string
Description
application/json

Request

DELETE

/messaging/conversations/:id

curl --location -g --request DELETE 'https://api.voxo.co/v2/messaging/conversations/:id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}'

Response

{
  "conversationId": 153
}

PATCHhttps://api.voxo.co/v2/messaging/conversations/name/:id

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
conversationName*
Type
string
Description
New conversation name

Header

Name
Authorization*
Type
string
Description
Bearer {accessToken}
Name
Content-Type*
Type
string
Description
application/json

Request

PATCH

/messaging/conversations/name/:id

curl --location -g --request PATCH 'https://api.voxo.co/v2/messaging/conversations/name/:id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}'

Response

{
  "conversationId": 153,
  "conversationName": "Friends"
}

PATCHhttps://api.voxo.co/v2/messaging/conversations/mark-read/:id

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.

Header

Name
Authorization*
Type
string
Description
Bearer {accessToken}
Name
Content-Type*
Type
string
Description
application/json

Request

PATCH

/messaging/conversations/mark-read/:id

curl --location -g --request PATCH 'https://api.voxo.co/v2/messaging/conversations/mark-read/:id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}'

Response

{
  "conversationId": 153,
}

GEThttps://api.voxo.co/v2/messaging/conversations?userId={userId}

List conversations

Retrieve text messaging conversations for a user

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

GET

/messaging/conversations?userId={userId}

curl --location -g --request GET 'https://api.voxo.co/v2/messaging/conversations?userId={userId}' \
--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": []
  }
]

GEThttps://api.voxo.co/v2/messaging/messages?userId={userId}&conversationId={conversationId}&page=1&recordsPerPage=100

Get messages

Retrieve the messages for a conversation

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

GET

/messaging/messages?userId=123&conversationId=123&page=1&recordsPerPage=100

curl --location -g --request GET 'https://api.voxo.co/v2/messaging/messages?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
}

GEThttps://api.voxo.co/v2/messaging/conversations/search?number={number}

Search your conversations

Retrieve the conversations where the number query is present

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

GET

/messaging/conversations/search?number=601602

curl --location -g --request GET 'https://api.voxo.co/v2/messaging/conversations/search?number={number}' \
--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"
  }
]