VOXO Docs

Messaging

POSThttps://api.voxo.co/v2/messaging/sendSMS

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/sendSMS
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"
},
POSThttps://api.voxo.co/v2/messaging/uploadMediaFiles

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/uploadMediaFiles
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" ]
POSThttps://api.voxo.co/v2/messaging/sendMMS

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/sendMMS
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"
}
GEThttps://api.voxo.co/v2/messaging/getProvisionedNumbers

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/getProvisionedNumbers
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
  }
]
POSThttps://api.voxo.co/v2/messaging/deleteConversation

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

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

Response

{
  "conversationId": 153
}
POSThttps://api.voxo.co/v2/messaging/updateConversationName

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

POST
/messaging/updateConversationName
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"
}
POSThttps://api.voxo.co/v2/messaging/markRead

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

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

Response

{
  "conversationId": 153,
}
GEThttps://api.voxo.co/v2/messaging/listConversations/{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/listConversations/1234
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": []
  }
]
GEThttps://api.voxo.co/v2/messaging/getMessages?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/getMessages?userId=123&conversationId=123&page=1&recordsPerPage=100
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
}
GEThttps://api.voxo.co/v2/messaging/searchConversations?number={number}

Search 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/searchConversations?number=601602
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"
  }
]