Download PDF
Download page SMS API.
SMS API
Introduction
The LiveVox Short Message Service (SMS) Application Programming Interface (API) provides methods that allow you to list SMS templates, send transactional SMS messages, and list client SMS codes.
See the LiveVox API Overview topic for a general description of how to interact with the API.
Prerequisites
- To obtain a valid Session ID, you must have successfully logged into the LiveVox platform. See Generating a Session ID for more information.
- To obtain an Access Token that is used in API requests, you must have an active subscription to the Configuration API. See Access Tokens for details.
- All messages in this API may be subject to rate limits and other restrictions.
User Roles
Unless otherwise specified in this documentation, to access any data through the SMS API, you must be a Sysadmin, Superuser, Manager, or Agent. These roles are defined in the LiveVox Configuration Manager and correspond to users who can access LiveVox configuration data through the LiveVox user interfaces.
API Methods
The SMS API provides various functionality, such as listing SMS templates and codes for sending transactional SMSes. Also, you can list channels, channel counts, and transaction history. In addition, thread and message functionalities are available to agents.
List Templates
Description: Returns the list of SMS templates for sending transactional SMSes.
User Roles: Agent, Sysadmin, Superuser, and Manager
Method: GET /sms/templates
Parameters:
None
Body:
None
Response Code: 200 OK
Body:
Key or Attribute | Type | Mandatory? | Description | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
templates | Array | Yes | An array of templates.
|
List Templates
#Request (JSON)
GET /sms/templates
Host: localhost.com
Content-Type: application/json
Accept: application/json
#Response (JSON)
200 OK
Content-Type: application/json
{
"templates": [
{
"id": 75870,
"message": "Hello reply yes for SMS Opt-In",
"smsCode": "53063",
"optInFlag": false
},
{
"id": 75959,
"description": "sms_blast",
"message": "APItest",
"smsCode": "53063",
"optInFlag": false
}
]
}
Send SMS
Description: Sends the transactional SMS message.
User Roles: Agent, Sysadmin, Superuser, and Manager
Method: POST /sms/
Parameters:
None
Body:
Key | Type | Agent Mandatory? | User Mandatory? | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
from | String | Yes | Yes | The short/long code from which to send the SMS. | ||||||||||||
to | String | Yes | Yes | Phone number to which to send the message. | ||||||||||||
body | Object | Yes | Yes | Content of the message.
Only one of the two fields must be present. They cannot both be empty or both be present. | ||||||||||||
account | String | Yes | No | The account with which the SMS message is associated. | ||||||||||||
serviceId | Integer | Not Applicable | Yes | The service ID from which you can send the SMS. Agents cannot include a service ID, the SMS is sent from the service they are logged into. |
Response Code: 200 OK
Body:
Key | Type | Mandatory? | Description |
---|---|---|---|
transactionId | Integer | Yes | The transaction ID associated with the sent SMS. |
Send SMS
#Request (JSON)
POST /sms/
Host: localhost.com
Content-Type: application/json
Accept: application/json
{
"from": "53063",
"to": "4154164061",
"serviceId": "100915",
"body": {
"templateId": "74257"
},
"account": "13213"
}
#Response
200 OK
Content-Type: application/json
{
"transactionId": 51644325690
}
List SMS Codes
Description: Returns a list of SMS codes for the service the agent/user is logged into.
User Roles: Agent, Sysadmin, Superuser, and Manager
Method: GET /sms/codes
Parameters:
None
Body:
None
Response Code: 200 OK
Body:
Key or Attribute | Type | Mandatory? | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
listSmsCodes | Array | Yes | An array of SMS codes.
|
List SMS Codes
#Request (JSON)
GET /sms/codes
Host: localhost.com
Content-Type: application/json
Accept: application/json
#Response (JSON)
200 OK
Content-Type: application/json
{
"listSmsCodes": [
{
"code": "14159174458",
"description": "Long_Code"
}
]
}
Agent
The Agent APIs provides functionalities to agents, like listing channels, channel count, and various other functionalities related to messages & their threads.
Some common terms used in the below sections:
Label | Allias | Description |
---|---|---|
Inbox | Group, Conversation Type | A top-level grouping of conversations that are either public or private. |
Thread | Conversation (Sometimes channel) | The thread or grouping of sent and received messages between an agent and customer. |
Interaction | Message | Individual message. In a number of cases, the |
Channel | MessageType | The message type category: SMS, Email, Chat, Voicemail, and Messaging (Whatsapp messages). |
List Channel Counts
Description: Provides a detailed list of counts of the agents current SMS inbox.
User Roles: Agent
Method: GET /sms/agent/interaction/counts/{agentId}
Parameters:
Attribute | Type | Mandatory? | Description |
---|---|---|---|
agentId | String | Yes | The agent ID. |
Body:
None
Response Code: 200 OK
Body:
Key or Attribute | Type | Mandatory? | Description |
---|---|---|---|
countOfEmailInteractionsSent | Number | No | The total number of emails sent by the agent. |
countOfSMSInteractionsSent | Number | No | The total number of SMSes sent by the agent. |
countOfMessageInteractionsSent | Number | No | The total number of Whatsapp messages sent by the agent. |
countOfUnreadEmailThreadsInPersonalInbox | Number | No | The total number of emails that are not read by the agent in the personal inbox. |
countOfReadEmailThreadsInPersonalInbox | Number | No | The total number of emails that are read by the agent in the personal inbox. |
countOfUnreadSMSThreadsInPersonalInbox | Number | No | The total number of SMSes that are not read by the agent in the personal inbox. |
countOfUnreadMessageInteractionsinPersonalInbox | Number | No | The total number of Whatsapp messages that are not read by the agent in the personal inbox. |
countOfReadSMSThreadsInPersonalInbox | Number | No | The total number of SMSes that are read by the agent in the personal inbox. |
countOfReadMessageInteractionsinPersonalInbox | Number | No | The total number of messages that are read by the agent in the personal inbox. |
countOfChatInteractionsAbandoned | Number | No | The total number of chat interactions that are abandoned. |
countOfOBWebChatInteractionsSent | Number | No | The total number of outbound web chat interactions that are sent by the agent. |
countOfIBWebChatInteractionReceived | Number | No | The total number of inbound web chat interactions that are received by the agent. |
countOfActiveSMSThreadsInPersonalInbox | Number | No | The total number of SMS conversations that are active in the agent's personal inbox. |
countOfActiveMessageThreadsinPersonalInbox | Number | No | The total number of Whatsapp conversations that are active in the agent's personal inbox. |
countOfActiveWebChatThreadsInPersonalInbox | Number | No | The total number of web chat conversations that are active in the agent's personal inbox. |
Get Channel Counts
#Request (JSON)
GET /sms/agent/interaction/counts/645836
Content-Type: application/json
Accept: application/json
#Response
200 OK
Content-Type: application/json
{
"countOfEmailInteractionsSent": 3,
"countOfSMSInteractionsSent": 0,
"countOfMessageInteractionsSent": 0,
"countOfUnreadEmailThreadsInPersonalInbox": 5,
"countOfReadEmailThreadsInPersonalInbox": 11,
"countOfUnreadSMSThreadsInPersonalInbox": 1,
"countOfUnreadMessageInteractionsinPersonalInbox": 0,
"countOfReadSMSThreadsInPersonalInbox": 2,
"countOfReadMessageInteractionsinPersonalInbox": 0,
"countOfChatInteractionsAbandoned": 0,
"countOfOBWebChatInteractionsSent": 0,
"countOfIBWebChatInteractionReceived": 0,
"countOfActiveEmailThreadsInPersonalInbox": 1,
"countOfActiveSMSThreadsInPersonalInbox": 0,
"countOfActiveMessageThreadsinPersonalInbox": 0,
"countOfActiveWebChatThreadsInPersonalInbox": 0
}
List Channel
Description: Look up a list of channels.
User Roles: Agent
Method: GET /sms/agent/channel
Parameters:
None
Body:
None
Response Code: 200 OK
Body:
Key or Attribute | Type | Mandatory? | Description | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Array | No |
|
Get Channel List
#Request (JSON)
GET /sms/agent/channel
Content-Type: application/json
Accept: application/json
#Response
200 OK
Content-Type: application/json
[
{
"channel": "Email",
"channelId": "645836",
"channelName": "Personal Email",
"unreadCount": 0,
"totalCount": 1,
"personal": true
},
{
"channel": "Voicemail",
"channelId": "9900001014",
"channelName": "Personal Voicemail 9900001014",
"unreadCount": 0,
"totalCount": 0,
"personal": true
},
{
"channel": "Voicemail",
"channelId": "9900001147",
"channelName": "Service 94981 VM",
"unreadCount": 0,
"totalCount": 0,
"personal": false
},
{
"channel": "Voicemail",
"channelId": "9900001025",
"channelName": "Service 94987 VM",
"unreadCount": 0,
"totalCount": 0,
"personal": false
},
{
"channel": "Voicemail",
"channelId": "9900001185",
"channelName": "Service 95047 VM",
"unreadCount": 0,
"totalCount": 0,
"personal": false
},
{
"channel": "Voicemail",
"channelId": "9900001016",
"channelName": "Service 95075 VM",
"unreadCount": 0,
"totalCount": 0,
"personal": false
}
]
Thread
Thread APIs allow you to list, assign, unassign, transfer, and resolve threads. In addition, you can list the available transfer agents.
List Threads
Description: Returns a list of threads within an inbox.
User Roles: Agent
Method: GET /agent/thread/details?channelId={}&personal={}&channel={}&pagination={}
Parameters:
Attribute | Type | Mandatory? | Description |
---|---|---|---|
channelId | String | Yes | If the personal flag is set to true, this is the |
personal | Boolean | No | Limit channels to those marked personal. |
channel | String | Yes | Type of channel (SMS, Email, Chat, Voicemail, and Messaging). |
pagination | Number | No | The pagination page number. |
Body:
None
Response Code: 200 OK
Body:
Key or Attribute | Type | Mandatory? | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Array | No |
|
List Threads
#Request (JSON)
GET /sms/agent/thread/details?channelId=94874&personal=true&channel=SMS&pagination=1
Content-Type: application/json
Accept: application/json
#Response
200 OK
Content-Type: application/json
[
{
"threadId": "56061444434",
"read": true,
"replied": true,
"fileSize": 0,
"channel": "SMS",
"details": "",
"to": "14154164061",
"serviceId": 94874,
"account": "1213",
"direction": 0
},
{
"threadId": "56047165976",
"read": true,
"replied": true,
"fileSize": 0,
"channel": "SMS",
"details": "",
"to": "14154164061",
"serviceId": 94874,
"account": "1213",
"direction": 0
},
{
"threadId": "56047127816",
"read": true,
"replied": true,
"fileSize": 0,
"channel": "SMS",
"details": "",
"to": "14154164061",
"serviceId": 94874,
"account": "1213",
"direction": 0
}
]
Assign Thread
Description: Moves the thread from the personal inbox to the group inbox.
User Roles: Agent
Method: PUT /sms/agent/thread/switchGroup/public?threadId={}
Parameters:
Attribute | Type | Mandatory? | Description |
---|---|---|---|
threadId | String | Yes | The thread ID. |
Body:
None
Response Code: 204 No Content
Body:
None
Assign Thread to Group Inbox
#Request (JSON)
PUT /sms/agent/thread/switchGroup/public?threadId=56047165976
Content-Type: application/json
Accept: application/json
#Response
204 No Content
Unassign Thread
Description: Moves the thread from the group inbox to the personal inbox.
User Roles: Agent
Method: PUT /sms/agent/thread/switchGroup/private?threadId={}&channelId={}
Parameters:
Attribute | Type | Mandatory? | Description |
---|---|---|---|
threadId | String | Yes | Thread ID of the SMS conversation. |
channelId | Number | Yes | The agent ID. |
Body:
None
Response Code: 204 No Content
Body:
None
Assign Thread to Personal Inbox
#Request (JSON)
PUT /sms/agent/thread/switchGroup/private?threadId=56047165976&channelId=795963
Content-Type: application/json
Accept: application/json
#Response
204 No Content
Transfer Thread
Description: Transfers the thread to another agent.
User Roles: Agent
Method: GET /sms/agent/thread/transfer?threadId={}&type={}&agentId={}
Parameters:
Attribute | Type | Mandatory? | Description |
---|---|---|---|
threadId | String | Yes | The thread ID for this interaction. |
type | ENUM | Yes | Type of channel (Voicemail, SMS, Email, Chat, Voice, Messaging). |
agentId | Long | Yes | The agent ID. |
Body:
None
Response Code: 200 OK
Body:
Attribute | Type | Mandatory? | Description |
---|---|---|---|
threadId | String | Yes | The confirmation ID. |
Transfer the Thread
#Request (JSON)
GET /sms/agent/thread/transfer?threadId=56047165976&type=SMS&agentId=645835
Content-Type: application/json
Accept: application/json
#Response
200 OK
Content-Type: application/json
{
"id": "56047165976"
}
List Transfer Agents
Description: Returns a list of agents who can accept a transfer.
User Roles: Agent
Method: GET /sms/agent/search?threadId={}
Parameters:
Key or Attribute | Type | Mandatory? | Description |
---|---|---|---|
threadId | String | Yes | The thread ID. |
Body:
None
Response Code: 200 OK
Body:
Key or Attribute | Type | Mandatory? | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Array | No |
|
List available Agents for Transfer
#Request (JSON)
POST /sms/agent/search?threadId=56070705625
Host: localhost.com
Content-Type: application/json
Accept: application/json
#Response
200 OK
Content-Type: application/json
[
{
"agentId": 645835,
"loginId": "KAVYA",
"name": "kavya livevox",
"status": "NOTREADY"
},
{
"agentId": 795963,
"loginId": "APITEST1",
"name": "apitest1 pass",
"status": "NOTREADY"
},
{
"agentId": 689581,
"loginId": "KAVYA3",
"name": "kavya3 livevox",
"status": "READY"
},
{
"agentId": 689579,
"loginId": "KAVYA1",
"name": "kavya11 livevox",
"status": "READY"
}
]
Resolve Thread
Description: Submits a term code for the thread.
User Roles: Agent
Method: POST /sms/agent/thread/resolve
Parameters:
None
Body:
Key or Attribute | Type | Mandatory? | Description |
---|---|---|---|
threadId | String | Yes | The thread ID for this interaction. |
termCodeId | Long | No | The termination code ID. |
account | String | Yes | Account of the contact for the interaction thread. |
agentEnteredAccount | String | Yes | Account of the contact for the interaction thread. |
Response Code: 204
Body:
None
Resolve Thread
#Request (JSON)
POST /sms/agent/thread/resolve
Content-Type: application/json
Accept: application/json
{
"account": "1213",
"threadId": "56061444734",
"agentEnteredAccount": "1213"
}
#Response
204 No Content
Messages
Messages APIs allow you to send, read, and unread a message.
Send SMS
Description: Sends an SMS.
This is a newer version of the Send SMS method for agents.
User Roles: Agent
Method: POST /sms/agent/message/send
Parameters:
None
Body:
Key or Attribute | Type | Mandatory? | Description |
---|---|---|---|
fromNumber | String | Yes | Phone number from which the SMS is sent. |
toNumber | String | Yes | Phone number to which the SMS is sent. |
templateId | Long | No | The SMS Template ID. |
message | String | Yes | SMS message. |
account | String | No | Account number of the customer. |
threadId | Long | No | The thread ID for this interaction. |
ticketId | Long | No | The ticket ID. |
crmAccountId | Long | No | The account ID in the CRM. |
Response Code: 200
Body:
Key or Attribute | Type | Mandatory? | Description |
---|---|---|---|
id | String | Yes | The transaction ID of the message. |
Send an SMS
#Request (JSON)
POST /sms/agent/message/send
Host: localhost.com
Content-Type: application/json
Accept: application/json
{
"fromNumber": "13345094836",
"toNumber": "4154164061",
"message": "API SMS Test sent by agent 2023-03-13T04:16:08.108Z",
"account": "1213"
}
#Response
200 OK
Content-Type: application/json
{
"id": "56284272387"
}
Mark Read
Description: Marks thread as read.
User Roles: Agent
Method: PUT /sms/agent/message/markAsRead?threadId={}&channelId={}
Parameters:
Attribute | Type | Mandatory? | Description |
---|---|---|---|
threadId | String | Yes | The thread ID for this interaction. |
channelId | String | Yes | The service ID. |
Body:
None
Response Code: 204 No Content
Body:
None
Mark Message as Read
#Request (JSON)
PUT /sms/agent/message/markAsRead?threadId=1229998286752&channelId=150321
Content-Type: application/json
Accept: application/json
#Response
204 No Content
Mark Unread
Description: Marks thread as unread.
User Roles: Agent
Method: PUT /sms/agent/message/markAsUnread?threadId={}&channelId={}
Parameters:
Attribute | Type | Mandatory? | Description |
---|---|---|---|
threadId | String | Yes | The thread ID for this interaction. |
channelId | String | Yes | The service ID. |
Body:
None
Response Code: 204 No Content
Body:
None
Mark Message as Unread
#Request (JSON)
GET /sms/agent/message/markAsUnread?threadId=56070705625&channelId=94874
Content-Type: application/json
Accept: application/json
#Response
204 No Content
List Transaction History
Description: Return list of transactions.
User Roles: Agent
Method: GET /sms/agent/messages?account={}&threadId={}
Parameters:
Attribute | Type | Mandatory? | Description |
---|---|---|---|
account | String | Yes | Account number of the customer. This is required if the |
threadId | String | No | The thread ID. This is required if the |
pagination | Number | No | The pagination page number. |
Body:
None
Response Code: 200 OK
Body:
Key or Attribute | Type | Mandatory? | Description | ||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Array | No |
|
List Transaction History
#Request (JSON)
GET /sms/agent/messages/?account=1213&threadId=56061444434
Content-Type: application/json
Accept: application/json
#Response
200 OK
Content-Type: application/json
[
{
"id": "56061451356",
"message": "API SMS Test Hi Kavita 2022-10-20T04:16:08.108Z",
"smsCode": "13345094836",
"phone": "14154164061",
"date": 1666263753000,
"status": "SMS MT Delivered",
"direction": "2"
},
{
"id": "56061451355",
"message": "API SMS Test sent by agent 2022-10-20T04:16:08.108Z",
"smsCode": "13345094836",
"phone": "14154164061",
"date": 1666263753000,
"status": "SMS MT Delivered",
"direction": "2"
},
{
"id": "56061451328",
"message": "Okay",
"smsCode": "13345094836",
"phone": "14154164061",
"date": 1666263132000,
"status": "Operator Transfer",
"direction": "1"
},
{
"id": "56061451327",
"message": "Good",
"smsCode": "13345094836",
"phone": "14154164061",
"date": 1666263117000,
"status": "Operator Transfer",
"direction": "1"
},
{
"id": "56061451326",
"message": "API SMS Test Hi Kavita 2022-10-20T04:16:08.108Z",
"smsCode": "13345094836",
"phone": "14154164061",
"date": 1666263103000,
"status": "SMS MT Delivered",
"direction": "2"
},
{
"id": "56061451325",
"message": "API SMS Test sent by agent 2022-10-20T04:16:08.108Z",
"smsCode": "13345094836",
"phone": "14154164061",
"date": 1666263102000,
"status": "SMS MT Delivered",
"direction": "2"
},
{
"id": "56061451220",
"message": "API SMS Test Hi Kavita 2022-10-20T04:16:08.108Z",
"smsCode": "13345094836",
"phone": "14154164061",
"date": 1666259109000,
"status": "SMS MT Delivered",
"direction": "2"
},
{
"id": "56061451219",
"message": "API SMS Test sent by agent 2022-10-20T04:16:08.108Z",
"smsCode": "13345094836",
"phone": "14154164061",
"date": 1666259108000,
"status": "SMS MT Delivered",
"direction": "2"
},
{
"id": "56061451207",
"message": "API SMS Test Hi Kavita 2022-10-20T04:16:08.108Z",
"smsCode": "13345094836",
"phone": "14154164061",
"date": 1666258736000,
"status": "SMS MT Delivered",
"direction": "2"
},
{
"id": "56061451206",
"message": "API SMS Test sent by agent 2022-10-20T04:16:08.108Z",
"smsCode": "13345094836",
"phone": "14154164061",
"date": 1666258735000,
"status": "SMS MT Delivered",
"direction": "2"
}
]
Errors
For more information, see the Errors section on the REST APIs page.