Getting Started with SMS Developer API
Integrate our powerful SMS Developer API into your application and start sending SMS messages within minutes. This guide walks you through the basic setup and first API call.
Step 1: Generate API Key
Login to your dashboard and navigate to the API Settings section to generate your unique API key.
Step 2: Base API Endpoint
All API requests are made to the following endpoint:
https://yourdomain.com/api/send-sms
Step 3: Sample cURL Request
Use the example below to send an SMS using cURL:
curl --request POST \
--url https://yourdomain.com/api/send-sms \
--header 'Content-Type: application/json' \
--data '{
"api_key": "YOUR_API_KEY",
"to": "919xxxxxxxxx",
"message": "Hello from the API!"
}'
Step 4: API Response
On success, the API returns a JSON response like:
{
"status": "success",
"message_id": "abc123",
"details": "Message sent successfully"
}
Troubleshooting
Ensure your API key is valid and your message content does not exceed 160 characters. Contact support for help.
Single SMS API
https://www.smsgatewayhub.com/ is a decade-old firm in the business.
Note: Additional parameters will be added in API EntityId
& dlttemplateid
.
TEXT Format
Response:
OTP SMS Format
Response:
UNICODE Format
Response:
GROUP SMS Format
Response:
FLASH Format
Response:
SCHEDULE SMS Format
Response:
Query Params
- APIKey: yourapicode
- senderid: yoursenderid
- channel: yourchannel
- DCS: your data coding value
- flashsms: your flash sms value
- number: recipient mobile number
- text: your sms content
- route: your route id
- schedtime: schedule date/time
- groupid: group id for numbers
Parameter Reference Table
Parameter |
Type |
Description |
APIKey | string | Use API KEY for authentication. |
senderid | string | Approved sender ID (6 chars). |
channel | string | Promotional=1, Transactional=2, OTP=OTP. |
DCS | string | 0 = normal, 8 = Unicode. |
flashsms | string | 0 = normal SMS, 1 = flash SMS. |
number | string | Recipient mobile number(s). |
text | text | Your SMS content. |
route | string | Route ID. |
schedtime | string | Format: yyyy/mm/dd hh:mm:ss PM. |
groupid | string | Group ID for numbers. |
EntityId | string | Registered Entity ID. |
dlttemplateid | string | DLT Template ID. |
telemarketerid | string | Telemarketer ID. |
SMSGATEWAYHUB is a decade old firm in the business of online bulk SMS services, catering to all types of customers, big, medium and small sized organizations through our innovative solutions for sending group text messages all over India through different sms gateway networks.
Bulk SMS API
https://www.smsgatewayhub.com/ is a decade-old firm in the business.
Note: Additional parameters will be added in API EntityId
& dlttemplateid
.
TEXT Format (Bulk)
Response:
OTP SMS Format
Response:
UNICODE Format (Bulk)
Response:
GROUP SMS Format
Response:
FLASH Format
Response:
SCHEDULE SMS Format
Response:
Query Params
- APIKey: yourapicode
- senderid: yoursenderid
- channel: yourchannel
- DCS: your data coding value
- flashsms: your flash sms value
- number: recipient mobile number
- text: your sms content
- route: your route id
- schedtime: schedule date/time
- groupid: group id for numbers
Parameter Reference Table
Parameter | Type | Description |
APIKey | string | Instead of the username and password you can use the API KEY for authentication of account. |
senderid | string | Approved sender id (6 characters string only). |
channel | string | Message channel Promotional=1 or Transactional=2 and OTP=OTP. |
DCS | string | Data coding value (Default is 0 for normal message, Set 8 for unicode sms). |
flashsms | string | Flash message immediate display (Default is 0 for normal sms, Set 1 for immediate display). |
number | string | Recipient mobile number (comma-separated). |
text | text | Your sms content. |
route | string | Route id to control delivery path. |
schedtime | string | Scheduled date/time (format: yyyy/mm/dd hh:mm:ss PM). |
groupid | string | Group id for contact groups. |
EntityId | string | Registered Entity Id. |
dlttemplateid | string | Registered DLT Template Id. |
telemarketerid | string | Registered Telemarketer Id. |
SMSGATEWAYHUB is a decade-old firm in the business of online bulk SMS services, catering to all types of customers through our innovative solutions.
International SMS API
https://www.smsgatewayhub.com/ is a decade-old firm in the business.
TEXT Format (Bulk)
Response:
UNICODE Format (Bulk)
Response:
GROUP SMS Format
Response:
FLASH Format
Response:
SCHEDULE SMS Format
Response:
Query Params
- APIKey: yourapicode
- senderid: yoursenderid
- channel: yourchannel
- DCS: your data coding value
- flashsms: your flash sms value
- number: recipient mobile number
- text: your sms content
- route: your route id
- schedtime: schedule date/time
- groupid: group id for numbers
Parameter Reference Table
Parameter |
Type |
Description |
APIKey | string | Instead of the username and password you can use the API KEYfor authentication of account. |
senderid | string | Approved sender id(6 characters string only). |
channel | string | Message channel Promotional=1, Transactional=2, OTP=OTP and INT=INT. |
DCS | string | Data coding value (Default is 0 for normal message, Set 8 for unicode sms). |
flashsms | string | Flash message immediate display (Default is 0 for normal sms, Set 1 for immediate display). |
number | string | Recipient mobile number (pass with comma seprated if need to send on more then one number) must required country code without * |
text | text | Your sms content. |
route | string | Pass the route id in this parameter to route the message. Click Here for more information regarding your routeid. |
schedtime | string | Schedule date and time for scheduling message (DateTime formate will be 2014/10/06 20:30:00 PM yyyy/mm/dd hh:mm:ss PM). |
groupid | string | group id for numbers. |
SMSGATEWAYHUB is a decade old firm in the business of online bulk SMS services, catering to all types of customers, big, medium and small sized organizations through our innovative solutions for sending group text messages all over India through different sms gateway networks.
Balance Check
https://www.smsgatewayhub.com/ is a decade-old firm in the business.
Note: Additional parameters will be added in API EntityId
& dlttemplateid
.
CHECK AVAILABLE BALANCE
Response:
Query Params
Parameter Reference Table
Parameter |
Type |
Description |
APIKey | string | Instead of the username and password you can use the API KEYfor authentication of account. |
SMSGATEWAYHUB is a decade old firm in the business of online bulk SMS services, catering to all types of customers, big, medium and small sized organizations through our innovative solutions for sending group text messages all over India through different sms gateway networks.
DLR Status
https://www.smsgatewayhub.com/ is a decade-old firm in the business.
TEXT Format
Response:
Query Params
- APIKey: yourapicode
- jobid: yourjobid
Parameter Reference Table
Parameter |
Type |
Description |
APIKey | string | Instead of the username and password you can use the API KEY for authentication of account. |
Jobid | string | You can use the Job Id check the message status. |
SMSGATEWAYHUB is a decade old firm in the business of online bulk SMS services, catering to all types of customers, big, medium and small sized organizations through our innovative solutions for sending group text messages all over India through different sms gateway networks.
Status/Error Codes
Error Code |
Description |
000 | Success |
001 | login details cannot be blank |
003 | sender cannot be blank |
004 | message text cannot be blank |
005 | message data cannot be blank |
006 | error: generic error description |
007 | username or password is invalid |
008 | account not actives |
009 | account locked, contact your account manager |
0010 | api restriction |
0011 | ip address restriction |
0012 | invalid length of message text |
0013 | mobile numbers not valid |
0014 | account locked due to spam message contact support |
0015 | senderid not valid |
0017 | groupid not valid |
0018 | multi message to group is not supported |
0019 | schedule date is not valid |
0020 | message or mobile number cannot be blank |
0021 | insufficient credits |
0022 | invalid jobid |
0023 | parameter missing |
0024 | invalid template or template mismatch |
0025 | {Field} can not be blank or empty |
0026 | invalid date range |
0027 | invalid optin user |
Embedding Codes
Character |
UTF-8 |
- | %2D |
! | %21 |
" | %22 |
# | %23 |
$ | %24 |
% | %25 |
& | %26 |
> | %3E |
< | %3C |
| %7F |
| ip address restriction |
' | invalid length of message text |
( | mobile numbers not valid |
) | account locked due to spam message contact support |
* | senderid not valid |
, | groupid not valid |
. | multi message to group is not supported |
/ | schedule date is not valid |
0 | message or mobile number cannot be blank |
1 | insufficient credits |
2 | invalid jobid |
3 | parameter missing |
4 | invalid template or template mismatch |
5 | {Field} can not be blank or empty |
6 | invalid date range |
7 | invalid optin user |
8 | invalid optin user |
9 | invalid optin user |
: | invalid optin user |
; | invalid optin user |
= | invalid optin user |
? | invalid optin user |
@ | invalid optin user |
[ | invalid optin user |
\ | invalid optin user |
] | invalid optin user |
^ | invalid optin user |
- | invalid optin user |
` | invalid optin user |
` | invalid optin user |
A | invalid optin user |
a | invalid optin user |
B | invalid optin user |
b | invalid optin user |
C | invalid optin user |
c | invalid optin user |
D | invalid optin user |
d | invalid optin user |
E | invalid optin user |
e | invalid optin user |
F | invalid optin user |
f | invalid optin user |
G | invalid optin user |
g | invalid optin user |
H | invalid optin user |
h | invalid optin user |
I | invalid optin user |
i | invalid optin user |
J | invalid optin user |
j | invalid optin user |
K | invalid optin user |
k | invalid optin user |
L | invalid optin user |
l | invalid optin user |
M | invalid optin user |
m | invalid optin user |
N | invalid optin user |
n | invalid optin user |
O | invalid optin user |
o | invalid optin user |
P | invalid optin user |
p | invalid optin user |
Q | invalid optin user |
q | invalid optin user |
R | invalid optin user |
r | invalid optin user |
S | invalid optin user |
s | invalid optin user |
T | invalid optin user |
t | invalid optin user |
U | invalid optin user |
u | invalid optin user |
V | invalid optin user |
v | invalid optin user |
W | invalid optin user |
w | invalid optin user |
X | invalid optin user |
x | invalid optin user |
Y | invalid optin user |
y | invalid optin user |
Z | invalid optin user |
z | invalid optin user |
Post Method
URL : https://www.smsgatewayhub.com/RestAPI/MT.svc/mt
Single Message
Response:
Multiple Message
Response:
Query Params
- User: yourusername
- Password: yourpassword
- senderid: yoursenderid
- channel: yourchannel
- DCS: your data coding value
- flashsms: your flash sms value
- number: recipient mobile number
- text: your sms content
- route: your route id
- schedtime: schedule date/time
- groupid: group id for numbers
Parameter Reference Table
Parameter |
Type |
Description |
User | string | Your system login name |
Password | string | Your system password |
senderid | string | Approved sender id(6 characters string only). |
channel | string | Message channel Promotional=1 or Transactional=2 and OTP=OTP. |
DCS | string | Data coding value (Default is 0 for normal message, Set 8 for unicode sms). |
flashsms | string | Flash message immediate display (Default is 0 for normal sms, Set 1 for immediate display). |
number | string | Recipient mobile number (pass with comma[,] seprated if need to send on more then one number). |
text | text | Your SMS content. |
route | string | Pass the route id in this parameter to route the message. Click Here for more information regarding your routeid. |
schedtime | string | Schedule date and time for scheduling message (DateTime formate will be 2014/10/06 20:30:00 PM yyyy/mm/dd hh:mm:ss PM). |
groupid | string | group id for numbers. |
Get Method
URL: https://www.smsgatewayhub.com/RestAPI/MT.svc/mt?data=
Single Message
Response:
Query Params
- User: yourusername
- Password: yourpassword
- senderid: yoursenderid
- channel: yourchannel
- DCS: your data coding value
- flashsms: your flash sms value
- number: recipient mobile number
- text: your sms content
- route: your route id
- schedtime: schedule date/time
- groupid: group id for numbers
Parameter Reference Table
Parameter |
Type |
Description |
User | string | Your system login name |
Password | string | Your system password |
senderid | string | Approved sender id(6 characters string only). |
channel | string | Message channel Promotional=1 or Transactional=2 and OTP=OTP. |
DCS | string | Data coding value (Default is 0 for normal message, Set 8 for unicode sms). |
flashsms | string | Flash message immediate display (Default is 0 for normal sms, Set 1 for immediate display). |
number | string | Recipient mobile number (pass with comma[,] seprated if need to send on more then one number). |
text | text | Your SMS content. |
route | string | Pass the route id in this parameter to route the message. Click Here for more information regarding your routeid. |
schedtime | string | Schedule date and time for scheduling message (DateTime formate will be 2014/10/06 20:30:00 PM yyyy/mm/dd hh:mm:ss PM). |
groupid | string | group id for numbers. |
Other Url
URL: https://www.smsgatewayhub.com/RestAPI/MT.svc/mt?data=
Balance Check
Response:
Delivery Report
Response:
Sender Id
Response:
Templates
Response:
Groups
Response:
Status/Error Codes
Error Code |
Description |
000 | Success |
001 | login details cannot be blank |
003 | sender cannot be blank |
004 | message text cannot be blank |
005 | message data cannot be blank |
006 | error: generic error description |
007 | username or password is invalid |
008 | account not actives |
009 | account locked, contact your account manager |
0010 | api restriction |
0011 | ip address restriction |
0012 | invalid length of message text |
0013 | mobile numbers not valid |
0014 | account locked due to spam message contact support |
0015 | senderid not valid |
0017 | groupid not valid |
0018 | multi message to group is not supported |
0019 | schedule date is not valid |
0020 | message or mobile number cannot be blank |
0021 | insufficient credits |
0022 | invalid jobid |
0023 | parameter missing |
0024 | invalid template or template mismatch |
0025 | {Field} can not be blank or empty |
0026 | invalid date range |
0027 | invalid optin user |
Misscall API
A copy of Missed call number & your Toll free number is forwarded to your predefined public URL.
URL Post Status: You can enable or disable url post i.e forwarding of a carbon copy of incoming Missed Call to your url
URL Details: You need to provide your complete url e.g http://yoursite.com/misscallhandler
When an incoming message for your Channel comes in, it will be forwarded to your URL as per following details (with the real values) –
The variables we send to you on the query string are :
- Caller: phone numer of the incoming sms
- Channel: Toll free number
- Circle: Circle of incoming missed call number
- Operator: Operator of incoming missed call number
- CallTime: Caller Called DateTime
- Dynamic Respone:You can enable or disable dynamic response as per your requirement. Once we post query string to your url, our server will wait for the response in case dynamic response is enabled. Remeber, dynamic response should be quick enough from your server other wise a time out error may occur.
Make sure there is no HTML is coming in your response.
Simple Voice SMS API
Resource
Parameters
Property Name |
Type |
Description |
from | string (919999999999) |
Numeric sender ID in E.164 format |
to* | string | | Destination address must be written in the international format (Example: 916666666666).
text | string | Message to be converted to speech and played to subscribers. Message text can be up to 1400 characters long. |
language | string(en) | If the message is in text format, the language in which the message is written must be defined for correct pronunciation. Below, in the Languages section, you can find the list of supported languages. If not set, default language is English [en]. |
voice | object | Used to define voice in which text would be synthesized. It has two parameters: name and gender. When only name is provided, then that exact voice with that name will be used to synthesize text. If only gender is provided, then text is synthesized with first voice in given gender. Gender can be male or female. If voice is not set, then default voice is used. |
audioFileUrl | string | Besides the text format of the message, audio recording (format like: wav, mp3, ogg etc.) can also be delivered as a voice message to the recipient. Audio file must be uploaded online so the existing URL can be available for the file download. Size of the audio file must be below 4 MB. |
Request Example
JSON
cURL :
PHP :
Ruby :
Python :
Java :
C# :
JavaScript :
Response :
200 OK - JSON
Response format
If successful, the response header HTTP status code will be 200 OK and the message will be sent.
If you try to send a message without authorization, you will receive the 401 Unauthorized error .
Voice Response
Parameter |
Type |
Description |
messages | VoiceResponseDetails |
Array of sent message objects, one object per every message. |
VoiceResponseDetails
Parameter |
Type |
Description |
to | String |
The message destination address. |
status | Status |
Indicates whether the message has been successfully sent, not sent, delivered, not delivered, waiting for delivery or any other possible status. |
Status
Parameter |
Type |
Description |
groupId | int |
Status group ID. |
groupName | String | Status group name. |
id | int | Status ID. |
name | String | Status name. |
description | String | Human-readable description of the status. |
Languages
Language |
Abbreviation |
NAME |
English (Indian) |
en-in |
Ravi |
Aditi
Heera (Default)
Priya
Raveena
|
Hindi |
hi |
Hemant |
Aadita (Default)
Kalpana
|
Multiple Voice SMS API
Resource
Parameters
Property Name |
Type |
Description |
from | string (919999999999) |
Numeric sender ID in E.164 format |
to* | array_string | | Array of message destination addresses. Destination address must be written in the international format (Example: 919999999999).
text | string | Text of the message that will be sent. Message text can be up to 1400 characters long. |
language | string(en) | If the message is in text format, the language the message is written in must be defined for correct pronunciation. Below, in the Languages section, you can find the list of supported languages. If not set, default language is English [en]. |
voice | object | Used to define voice in which text would be synthesized. It has two parameters: name and gender. When only name is provided, then that exact voice with that name will be used to synthesize text. If only gender is provided, then text is synthesized with first voice in given gender. Gender can be male or female. |
audioFileUrl | string | Besides the text format of the message, audio recording (format like: wav, mp3, ogg, etc.) can also be delivered as a voice message to the recipient. Audio file must be uploaded online so the existing URL can be available for the file download. Size of the audio file must be below 4 MB. |
Fully Featured Voice API
Resource
Parameters
Property Name |
Type |
Description |
bulkId | string |
The ID which uniquely identifies the request. |
from | string-919999999999 |
Numeric sender ID length should be between 3 and 14 characters. |
to* | array_string | | Array of message destination addresses. Destination address must be written in the international format (Example: 919999999999).
messageId | string | | The ID that uniquely identifies the message sent.
text | string | Text of the message that will be sent. Pause between words is possible. Message text can be up to 1400 characters long. |
language | string(en) | If the message is in text format, language in which the message is written must be defined for correct pronunciation. Below, in the Languages section, you can find the list of languages that we support. If not set, default language is English [en]. |
voice | object | Used to define voice in which text would be synthesized. It has two parameters: name and gender. When only name is provided, then that exact voice with that name will be used to synthesize text. If only gender is provided, then text is synthesized with first voice in given gender. Gender can be male or female. If voice is not set, then default voice is used. |
audioFileUrl | string | Besides the text format of the message, audio recording (format like: wav, mp3, ogg, etc.) can also be delivered as a voice message to the recipient. Audio file must be uploaded online so the existing URL can be available for the file download. Size of the audio file must be below 4 MB. |
speechRate | double (1) | The reproduction speed of speech in the resulting message. Effective only when using text. Supported range is from 0.5 (slow down speech) to 2 (speed up speech). Values less than 0.5 will be replaced with 0.5, and values higher than 2 will be replaced with 2. |
notifyUrl | string | The URL on your callback server on which the Delivery report will be sent. |
notifyContentType | notifyContentType | Preferred Delivery report content type. Can be application/json or application/xml. |
validityPeriod | int | The message validity period shown in minutes. When the period expires, it will not be allowed for the message to be sent. A validity period longer than 48h is not supported (in this case, it will be automatically set to 48h). |
sendAt | datetime | Used for scheduled Voice messages (message not to be sent immediately, but at scheduled time). |
record | boolean | Record the call and expose it to client as URL inside the delivery report. Can be true or false. |
repeatDtmf | string | Response (DTMF) code which enables repeating message if a subscriber enters it. |
maxDtmf | int int(0) | Defines the max number of dtmf codes entered by end user that would be received. |
ringTimeout | int (45) | The duration of the call prior to answer shown in seconds, unless there are no operator limitations. |
dtmfTimeout | int (10) | The waiting period for end user to enter dtmf digits. |
callTimeout | int | Total call period shown in seconds. |
callTransfers | array_object | Possible call transfer scenario defined as JSON object. See example below |
processKey | string | Key that uniquely identifies Conversion tracking process. |
retry | object | Used to define if the delivery of the Voice messages should be retried in case the first try doesn't succeed. Additional retries will be made according to the schedule defined by minPeriod and maxPeriod parameters and platform's internal retry logic. If the minPeriod differs maxPeriod, delivery will be retried in the following manner: after 1 min, 2 min, 5 min, 10 min, 20 min, 30 min, 1 hour, 2 hours, 4 hours, 8 hours, 16 hours, 24 hours or until maxPeriod is reached. If the retry attempt for the MaxPeriod is reached, the MaxPeriod will be used for all subsequent retries. If the minPeriod and the maxPeriod are defined as equal values, the period of time between retries will be equal to this value. Message delivery will be retried until the successful delivery or message validity or maxCount value is reached. |
minPeriod | int | Defines the minimal waiting time (in minutes) after the previous failed attempt to try to deliver the message again. |
maxPeriod | int | Defines the maximum waiting time (in minutes) after the previous failed attempt to try to deliver the message again. |
maxCount | int | Specify the maximum number of retry attempts. Maximum value of the maxCount is 4. Higher value, if entered will be set to 4. |
sendingSpeed | object | Sending rate defined in number of messages sent per second, minute, hour or day. First message will be sent immediately (or at sendAt time if scheduling is used) and subsequent messages will be sent respecting defined speed. For example, if sendingSpeed is defined as 10 messages per hour, messages will be sent every 6 minutes. If this parameter is defined, validityPeriod is ignored. |
speed | int | Defines the number of messages that will be sent per specified time unit. |
timeUnit | string | Defines time unit used for calculating sending speed. Possible values: second, minute, hour and day. |
machineDetection | string | Used for enabling detection of answering machine after the call has been answered. It can be set to "hangup" or "continue". When set to "hangup", if a machine is detected call is hung up. When set to "continue", if a machine is detected, then voice message starts playing into voice mail after the answering message is finished with its greeting. If machineDetection is used, there is a minimum of 4 seconds detection time, which can result in delay of playing the message. Answering machine detection is additionally charged. For more information please contact your account manager. |
Response
200 OK
Response format
If successful, the response header HTTP status code will be 200 OK and the message will be sent.
If you try to send the message without authorization, you will receive a 401 Unauthorized error.
Voice Response
Parameter |
Type |
Description |
bulkId | String | The ID that uniquely identifies the request. Bulk ID will be received when a message is sent to more than one destination address. |
messages | VoiceResponseDetails | Array of sent message objects, one object per every message. |
VoiceResponseDetails
Parameter |
Type |
Description |
to | String |
The message destination address. |
status | Status | Indicates whether the message has been sent successfully, not sent, delivered, not delivered, waiting for delivery or any other possible status. |
messageId | String | The ID that uniquely identifies the sent message. |
Status
Parameter |
Type |
Description |
groupId | int |
Status group ID. |
groupName | String | Status group name. |
id | int | Status ID. |
name | String | Status name. |
description | String | Human-readable description of the status. |
Pause between words
Adding pauses between the words and extending the duration of the voice message is possible by using the comma character ",".
For example, if you want to have a 3 second pause after each word, then the text parameter should look like this "one,,,,,,two,,,,,,three,,,,,,". Each coma creates a pause of 0,5 seconds.
Ring timeout limitations
There are no limitations on the Voice platform regarding this value, however, most of the operators have their own ring timeout limitations and it is advisable to keep the ringTimeout value up to 45s.
Call Transfers
Using call transfer, you can send an interactive message to your subscribers, providing them the opportunity to respond by pressing their phone keys. When your subscriber chooses a number call transfer will redirect a call to the set number. The Field is JSON formatted.
Call transfer for any DTMF
Call transfer for specific DTMF
API response
Delivery Reports
Resource
Parameters
Property Name |
Type |
Description |
bulkId | string | The ID that uniquely identifies the request. Bulk ID will be received only when you send a message to more than one destination address. |
messageId | string |
The ID that uniquely identifies the message sent. |
limit | string | The maximum number of returned delivery reports. Default value is 50. |
Request Example
JSON
Response
200 OK
Response format
If successful, the response header HTTP status code will be 200 OK and delivery reports will be returned in the response body.
If you try to send a message without authorization, you will get a response with the HTTP status code 401 Unauthorized.
VoiceReportResponse
Parameter |
Type |
Description |
results | VoiceReport | Collection of reports, one per every message. |
VoiceReport
Parameter |
Type |
Description |
bulkId | String | Bulk ID. |
messageId | String | Message ID. |
to | String | Destination address. |
sentAt | Date | Tells when the voice message was sent. Has the following format: yyyy-MM-dd'T'HH:mm:ss.SSSZ. |
doneAt | Date | Tells when the voice message was processed by Infobip (ie. delivered to destination, delivered to destination network, etc.). |
startTime | Date | Tells when the voice message call was established and started ringing. |
endTime | Date | Tells when the voice message call was ended. |
answerTime | Date | Tells when the voice message call was answered. |
duration | int | Duration of the Voice message call. |
fileDuration | Double | Duration of the Voice message audio file. |
mccMnc | String | Mobile country and network codes. |
callbackData | String | Callback data sent through callbackData field in fully featured Voice message. |
dtmfCodes | String | DTMF code entered by user. |
recordedAudioFileUrl | String | URL to retrieve recorded calls that were made by messages with the record feature activated. |
price | Price | Sent voice message price. |
status | Status | Indicates whether the message is successfully sent, not sent, delivered, not delivered, waiting for delivery or any other possible status. |
error | Error | Indicates whether the error occurred during the query execution. |
Price
Parameter |
Type |
Description |
pricePerSecond | BigDecimal | Price per one second of the voice message. |
currency | String | The currency in which the price is expressed. |
Status
Parameter |
Type |
Description |
groupId | int | Status group ID. |
groupName | String | Status group name. |
id | int | Status ID. |
name | String | Status name. |
description | String | Human-readable description of the status. |
Error
Parameter |
Type |
Description |
groupId | int | Error group ID. |
groupName | String | Error group name. |
id | int | Error ID. |
name | String | Error name. |
description | String | Human-readable description of the Error. |
permanent | boolean | Tells if the error is permanent. |
Recorded Audio File
If the option to record was enabled, the response will contain the recordedAudioFileUrl field. Using that URL with GET method will initiate the download of the recorded file. If using a REST testing client, make sure to save the downloaded data instead of displaying it in the client's response area. Recordings are encoded as PCM WAVE signed little-endian 16bit 8kHz audio files.
DELIVERY REPORT WILL BE RETURNED ONLY ONCE!
Delivery reports are returned only once. Additional delivery report request will return an empty collection.
Additional examples
Getting reports without any query parameter
Request :
Response
JSON :
XML :
Getting reports without any query parameter
Request :
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"results":[
{
"bulkId":"80664c0c-e1ca-414d-806a-5caf146463df",
"messageId":"bcfb828b-7df9-4e7b-8715-f34f5c61271a",
"to":"38598111",
"sentAt":"2015-02-12T09:58:20.323+0100",
"doneAt":"2015-02-12T09:58:20.337+0100",
"startTime": "2018-06-25T13:38:15.000+0000",
"endTime": "2018-06-25T13:38:28.316+0000",
"answerTime": "2018-06-25T13:38:25.000+0000",
"duration":10,
"fileDuration": 19.3,
"mccMnc": "21901",
"callbackData": "DLR callback data",
"dtmfCodes":"1",
"recordedAudioFileUrl":"/tts/3/files/bcfb828b-7df9-4e7b-8715-f34f5c61271a/38598111",
"price":{
"pricePerSecond":0.01,
"currency":"EUR"
},
"status":{
"groupId":3,
"groupName":"DELIVERED",
"id":5,
"name":"DELIVERED_TO_HANDSET",
"description":"Message delivered to handset"
},
"error":{
"groupId":0,
"groupName":"OK",
"id": 5000,
"name": "VOICE_ANSWERED",
"description": "Call answered by human",
"permanent": true
}
},
{
"bulkId":"08fe4407-c48f-4d4b-a2f4-9ff583c985b8",
"messageId":"12db39c3-7822-4e72-a3ec-c87442c0ffc5",
"to":"385981112",
"sentAt":"2015-02-12T09:58:20.345+0100",
"doneAt":"2015-02-12T09:58:20.350+0100",
"duration":10,
"mccMnc": "21901",
"callbackData": "DLR callback data",
"dtmfCodes":"1",
"recordedAudioFileUrl":"/tts/3/files/12db39c3-7822-4e72-a3ec-c87442c0ffc5/385981112",
"price":{
"pricePerSecond":0.01,
"currency":"EUR"
},
"status":{
"groupId":3,
"groupName":"DELIVERED",
"id":5,
"name":"DELIVERED_TO_HANDSET",
"description":"Message delivered to handset"
},
"error":{
"groupId":0,
"groupName":"OK",
"id": 5000,
"name": "VOICE_ANSWERED",
"description": "Call answered by human",
"permanent": true
}
}
]
}
XML :
Voice Message logs
Resource
Parameters
Property Name |
Type |
Description |
from | string | Sender ID that can be numeric. |
to | string | The message destination address. |
bulkId | string | The ID which uniquely identifies the request. |
messageId | string | The ID that uniquely identifies the message sent. |
generalStatus | string | Sent voice message status group. Indicates whether the message has been successfully sent, not sent, delivered, not delivered, waiting for delivery or any other possible status. |
sentSince | datetime | Lower the limit on the date and time of voice message sending. |
sentUntil | datetime | The upper limit on the date and time of voice message sending. |
limit | int | Maximal number of messages in the returned logs. Default value is 50. |
mcc | string | Mobile country code. |
mnc | string | Mobile network code. |
Request Example
JSON
Request Example
200 OK
Response format
If successful, the response header HTTP status code will be 200 OK and the message logs will be returned.
If you try to send the message without authorization, you will get a response with HTTP status code 401 Unauthorized.
If you use this method too many times in a short period of time, you will get the status code 429 Too Many Requests. This prevents misusing logs in cases where reports would be more appropriate. For more information about when to use logs, please see the documentation.
VoiceLogsResponse
VoiceReportResponse
Parameter |
Type |
Description |
results | VoiceLog | Collection of logs. |
VoiceLog
Parameter |
Type |
Description |
bulkId | String | The ID that uniquely identifies the request. |
messageId | String | The ID that uniquely identifies the message sent. |
to | String | The message destination address. |
from | String | Sender ID that can be alphanumeric or numeric. |
text | String | Text of the message that was sent. |
sentAt | Date | Tells when the voice message was sent. Has the following format: yyyy-MM-dd'T'HH:mm:ss.SSSZ. |
doneAt | Date | Tells when the voice message was processed by Infobip (ie. delivered to destination, delivered to destination network, etc.) |
duration | int | Call duration in seconds. |
mccMnc | String | Mobile country and network codes. |
price | Price | Sent voice message price. |
status | Status | Indicates whether the message has been successfully sent, not sent, delivered, not delivered, waiting for delivery or any other possible status. |
error | Error | Indicates whether the error occurred during the query execution. |
Price
Parameter |
Type |
Description |
pricePerSecond | BigDecimal | Price per one second of the voice message. |
currency | String | The currency in which the price is expressed. |
Status
Parameter |
Type |
Description |
groupId | int | Status group ID. |
groupName | String | Status group name. |
id | int | Status ID. |
name | String | Status name. |
description | String | Human-readable description of the status. |
Error
Parameter |
Type |
Description |
groupId | int | Error group ID. |
groupName | String | Error group name. |
id | int | Error ID. |
name | String | Error name. |
description | String | Human-readable description of the Error. |
permanent | boolean | Tells if the error is permanent. |
Additional examples
Getting logs without any query parameter
This request will return the last 50 message logs from the previous 48h by default.
Request :
Python :
{
"results":[
{
"bulkId":"06479ba3-5977-47f6-9346-fee0369bc76b",
"messageId":"1f21d8d7-f306-4f53-9f6e-eddfce9849ea",
"to":"916666666666",
"from":"919999999999",
"text":"Test voice message.",
"sentAt":"2015-02-23T17:40:31.773+0100",
"doneAt":"2015-02-23T17:40:31.787+0100",
"duration":10,
"mccmnc":"22801",
"price":{
"pricePerSecond":0.01,
"currency":"EUR"
},
"status":{
"groupId":3,
"groupName":"DELIVERED",
"id":5,
"name":"DELIVERED_TO_HANDSET",
"description":"Message delivered to handset"
},
"error":{
"groupId":0,
"groupName":"OK",
"id": 5003,
"name": "EC_VOICE_NO_ANSWER",
"description": "User was notified, but did not answer call",
"permanent": true
}
}
]
}
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "http://vapi.smsgatewayhub.com/tts/3/logs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_POSTFIELDS => "",
CURLOPT_HTTPHEADER => array(
"accept: application/json",
"authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
?>
require 'uri'
require 'net/http'
url = URI("http://vapi.smsgatewayhub.com/tts/3/logs")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["authorization"] = 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
response = http.request(request)
puts response.read_body
import http.client
conn = http.client.HTTPConnection("vapi.smsgatewayhub.com")
payload = ""
headers = {
'authorization': "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
'content-type': "application/json",
'accept': "application/json"
}
conn.request("GET", "/tts/3/logs", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Response :
JSON
HTTP/1.1 200 OK
Content-Type: application/json
{
"results":[
{
"bulkId":"bafdeb3d-719b-4cce-8762-54d47b40f3c5",
"messageId":"07e03aae-fabc-44ad-b1ce-222e14094d70",
"to":"916666666666",
"from":"919999999999",
"text":"Test voice message 1.",
"sentAt":"2015-02-23T17:41:11.833+0100",
"doneAt":"2015-02-23T17:41:11.843+0100",
"duration":10,
"mccmnc":"22801",
"price":{
"pricePerSecond":0.01,
"currency":"EUR"
},
"status":{
"groupId":3,
"groupName":"DELIVERED",
"id":5,
"name":"DELIVERED_TO_HANDSET",
"description":"Message delivered to handset"
},
"error":{
"groupId":0,
"groupName":"OK",
"id": 5003,
"name": "EC_VOICE_NO_ANSWER",
"description": "User was notified, but did not answer call",
"permanent": true
}
},
{
"bulkId":"06479ba3-5977-47f6-9346-fee0369bc76b",
"messageId":"1f21d8d7-f306-4f53-9f6e-eddfce9849ea",
"to":"916666666666",
"from":"919999999999",
"text":"Test voice message 2.",
"sentAt":"2015-02-23T17:40:31.773+0100",
"doneAt":"2015-02-23T17:40:31.787+0100",
"duration":10,
"mccmnc":"22801",
"price":{
"pricePerSecond":0.01,
"currency":"EUR"
},
"status":{
"groupId":3,
"groupName":"DELIVERED",
"id":5,
"name":"DELIVERED_TO_HANDSET",
"description":"Message delivered to handset"
},
"error":{
"groupId":0,
"groupName":"OK",
"id": 5003,
"name": "EC_VOICE_NO_ANSWER",
"description": "User was notified, but did not answer call",
"permanent": true
}
}
]
}
XML
Getting logs with from, to and limit as filters
This request will filter final messages according to the rule - all messages sent from from, return last limit messages with destinations to.
Request :
Response :
JSON
XML
Getting logs filtered by multiple bulkIds
This request will return messages that have bulkId among the specified bulkIds in the filter.
Request :
Response :
JSon
HTTP/1.1 200 OK
Content-Type: application/json
{
"results":[
{
"bulkId":"bafdeb3d-719b-4cce-8762-54d47b40f3c5",
"messageId":"07e03aae-fabc-44ad-b1ce-222e14094d70",
"to":"916666666666",
"from":"919999999999",
"text":"Test voice message 1.",
"sentAt":"2015-02-23T17:41:11.833+0100",
"doneAt":"2015-02-23T17:41:11.843+0100",
"duration":10,
"mccmnc":"22801",
"price":{
"pricePerSecond":0.01,
"currency":"EUR"
},
"status":{
"groupId":3,
"groupName":"DELIVERED",
"id":5,
"name":"DELIVERED_TO_HANDSET",
"description":"Message delivered to handset"
},
"error":{
"groupId":0,
"groupName":"OK",
"id": 5003,
"name": "EC_VOICE_NO_ANSWER",
"description": "User was notified, but did not answer call",
"permanent": true
}
},
{
"bulkId":"06479ba3-5977-47f6-9346-fee0369bc76b",
"messageId":"1f21d8d7-f306-4f53-9f6e-eddfce9849ea",
"to":"916666666666",
"from":"919999999999",
"text":"Test voice message 2.",
"sentAt":"2015-02-23T17:40:31.773+0100",
"doneAt":"2015-02-23T17:40:31.787+0100",
"duration":10,
"mccmnc":"22801",
"price":{
"pricePerSecond":0.01,
"currency":"EUR"
},
"status":{
"groupId":3,
"groupName":"DELIVERED",
"id":5,
"name":"DELIVERED_TO_HANDSET",
"description":"Message delivered to handset"
},
"error":{
"groupId":0,
"groupName":"OK",
"id": 5003,
"name": "EC_VOICE_NO_ANSWER",
"description": "User was notified, but did not answer call",
"permanent": true
}
}
]
}
XML
Getting logs filtered by date range and general status
This request will return messages with the status that matches the generalStatus parameter (see Response codes) which are sent between sentSince and current time.
Request :
Response :
JSon
XML
Get Voices
Resource
Property Name |
Type |
Description |
language | string | Language abbreviation. (e.g. "en"). In the Languages section, you can find the list of supported languages. |
Response for /tts/3/voices/en
JSON
Bad request example:
JSON
Response :
JSON
Voice Messages Schedule Information and Status
Fully featured voice messages API allows you to send advanced voice messages that will not be sent immediately, but at a scheduled time (scheduled voice messages) by setting the sendAt parameter.
Using Sending speed on Fully featured voice messages also results with the campaign being scheduled. This means that the messages will not be sent as the bulk immediately all at once but rather as a scheduled campaign, with some delay between the messages depending on the sending speed being used. Message scheduling and status API enables you to control message delivery schedule and message status.
Message scheduling:
- Get message schedule info
- Reschedule voice message
- channel: yourchannel
Message status:
- Get message status info
- Update message status
Get message schedule info
This method will return information about the scheduled time for a unique bulk message. Canceling and rescheduling are supported only when the Fully featured voice message request contains at least one message and the message bulkId is unique.
Request example:
JSON
Response
JSON
Reschedule voice message
Messages scheduled with the sendAt or Sending speed parameter can be paused, resumed or canceled by changing the message status, or rescheduled using the bulkId parameter as an identifier.
RESCHEDULING AND STATUS UPDATE REQUIREMENTS
Please note that canceling and rescheduling is supported only when the Fully featured voice message request contains at least one message per bulk and the message bulkId is unique. If you don't provide the bulkId through the initial voice message request, the system will create a unique id for you and include it as bulkId in response. This ID can be used later to retrieve delivery information, change status and date/time of message delivery.
Request example:
JSON
Response:
JSON
Get message status info
This method will return the status of the bulk message.
Request example:
JSON
Response:
JSON
Possible status to be returned |
Meaning of the status |
PENDING | Sending will start in a scheduled time |
PAUSED | Sending is paused |
CANCELED | Sending was canceled |
PROCESSING | Sending in the progress |
FINISHED | All the messages were sent |
Update message status
Messages scheduled with the sendAt or sending speed parameter can be paused, resumed or canceled by changing the message status, or rescheduled using the bulkId parameter as an identifier.
Only voice messages that were not already sent will be canceled.
RESCHEDULING AND STATUS UPDATE REQUIREMENTS
Please note that cancelling and rescheduling is supported only when the Fully featured voice message request contains only one message per bulk and the message bulkId is unique. If you don't provide the bulkId through the initial advanced voice message send request, the system will create a unique id for you and include it as bulkId in response. This ID can be used later to retrieve delivery information, change status and date/time of message delivery.
STATUS UPDATE
PENDING and PAUSED statuses can be changed back and forth until the message starts to process (scheduled time is up, and the message is sent). Once a message is CANCELED, it cannot be rescheduled or updated with a new status! The message will remain undelivered regardless of the scheduled date and time.
Request example:
JSON
Response:
JSON
Developer API