Telenor Corporate Call & SMS

API Documentation

1
 Table of Contents
1. Authentication & Session ID................................................................................................................................ 3
2. Sending a Quick Message .................................................................................................................................... 4
3. Query a Quick Message....................................................................................................................................... 5
4. Create a Subscriber List ....................................................................................................................................... 6
5. Add Subscribers to a Subscriber List ................................................................................................................... 7
6. Create an SMS Campaign .................................................................................................................................... 8
7. Query an SMS Campaign ..................................................................................................................................... 9
8. Ping.................................................................................................................................................................... 10
9. Sending a Quick Call .......................................................................................................................................... 11
10. Query a Quick Call ............................................................................................................................................. 12
11. Get Incoming SMS Information ......................................................................................................................... 13
12. Action on Unpaid Pending Incoming SMS ......................................................................................................... 14
13. Fetching Pending Paid Incoming SMS ............................................................................................................... 15
14. Upload Audio File .............................................................................................................................................. 16
15. Check Uploaded Audio File Status..................................................................................................................... 17
16. Create a Voice Broadcast Campaign ................................................................................................................. 18
17. Create a Voice Feedback Campaign .................................................................................................................. 19
18. Create a Voice Dynamic Campaign ................................................................................................................... 20
19. Query a Voice Campaign ................................................................................................................................... 21
22. Balance Inquiry ................................................................................................................................................. 24
23. Appendix - A...................................................................................................................................................... 25
24. Appendix - B ...................................................................................................................................................... 26
25. Appendix - C ...................................................................................................................................................... 27
26. Appendix - D...................................................................................................................................................... 28
27. Appendix - E ...................................................................................................................................................... 29
28. Appendix - F ...................................................................................................................................................... 30
29. Appendix - G ..................................................................................................................................................... 31

2
 1. Authentication & Session ID
In order to deliver a message, the system needs to authenticate the request as coming from a valid source. The
following parameters are used to achieve this:

msisdn: This is the Mobile Number for your Corporate Call & SMS Account
password: This is the current password you have set for your Account

You can have multiple threads open, however the session ID will expire after 30 minutes of inactivity. You will
then have to re-authenticate to receive a new session ID.

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/auth.jsp?msisdn=xxxx&password=xxx

Success Response:
<?xml version="1.0" encoding="UTF-8" ?>
<corpsms>
<command>Auth_request</command>
<data>Session ID</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8" ?>
<corpsms>
<command>Auth_request</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

NOTE: This Session ID must be used with all future commands to the API.

3
 2. Sending a Quick Message
This command is used to send a Quick Message. To send a quick message, the destination address should be in
the format 923xxxxxxxxx. The basic parameters required are:

session_id: The session ID returned from authentication

to: Comma separated list of destination mobile numbers
text: The content of the message
mask: The mask to be used to send the message.
unicode (optional): If the text of the SMS is in any language other than English, this
parameter must be sent to TRUE.
e.g., If the text is in Urdu, an extra parameter unicode=true must be
passed with the request
operator_id (optional): If the SMS is to be sent through a specific operator, this field should
contain ID for the respective operator.
List of operators is mentioned in Appendix D.

Each message returns a unique identifier in the form of Message ID. For multiple destination numbers, a
comma separated list of message ID's is returned. Single message ID is returned for each mobile number.
If even a single mobile number is in incorrect format, the request will be rejected. The message ID can be used
to track and monitor any given message. The message ID is returned after each post.

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/sendsms.jsp?session_id=xxxx&to=923xxxxxxxxx,923xxxxxxxx
x,923xxxxxxxxx&text=xxxx&mask=xxxx

Success Response:
<?xml version="1.0" encoding="UTF-8" ?>
<corpsms>
<command>Submit_SM</command>
<data>Message ID1,Message ID2,Message ID3</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8" ?>
<corpsms>
<command>Submit_SM</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

4
 3. Query a Quick Message
This command returns the status of a quick message. You can query the status with the msg_id which is the
message ID returned by the Gateway when a message has been successfully submitted.
For authentication you need to pass session_id as well while querying for the message status. For
description on the status returned, please refer Appendix B.

session_id: The session ID returned from authentication

msg_id: The Message ID returned in response to the command executed in Step2

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/querymsg.jsp?session_id=xxx&msg_id=xxxx

Success Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Message_query</command>
<data>STATUS</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Message_query</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

5
 4. Create a Subscriber List
This command can be used to create a list of subscribers which can then be used to send the message in a
campaign. The basic parameters required are:

session_id: The session ID returned from authentication

list_name: The name you want to give to this list

The response in case of success will contain a List ID which can later be used to add the subscribers to this list or
to send the message to this list in a campaign.

Example - GET:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/list.jsp?session_id=xxx&list_name=xxxx

Success Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Create_MLIST</command>
<data>List ID</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Create_MLIST</command>
<data>Error Code</data>
<response>ERROR</response>
</corp

6
 5. Add Subscribers to a Subscriber List
This command is used to add subscribers to an already created subscriber list. The basic parameters required
are:

session_id: The session ID returned from authentication

list_id: The list ID to which the subscribers need to be added
to: The comma separated list of mobile numbers in international
format (92345xxxxxxx) that need to be added to this list

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/addcontacts.jsp?session_id=xxx&list_id=xxx&to=xxxx

Success Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>add_to_LIST</command>
<data>List ID</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>add_to_LIST</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

Example POST:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/addcontacts.jsp?session_id=xxx&list_id=xxx

comma separated list of misdns to be added in request body

Success Response:
<?xml version="1.0" encoding="UTF-8" ?>
<corpsms>
<command>add_to_LIST</command>
<data>List ID</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8" ?>
<corpsms>
<command>add_to_LIST</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

7
 6. Create an SMS Campaign
This command can be used to send a message to lists of subscribers at specified time. The basic parameters
required are:

session_id: The session ID returned from authentication

name: The name you want to give to this campaign.
group_ids: The comma-separated list of group IDs (subscriber list IDs) you want to
send the message to.
text: The content of the message to be sent
time: The date and time at which the message is to be sent. The time should
be in format yyyy-MM-ddHH:mm:ss e.g. 2009-09-15 10:15:00
mask: The mask to be used for the campaign.

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/campaign.jsp?session_id=xxxx&name=xxxx&group_ids=xx
xx&text=xxxx&time=xxxx&mask=xxxx

Success Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Create_CAMP</command>
<data>Campaign ID</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Create_CAMP</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

8
 7. Query an SMS Campaign
This command returns the status of all MSISDNs used in the campaign. You can query the status with the
campid which is the campaign ID returned by the Gateway when a campaign has been successfully submitted.
For authentication you need to pass session_id as well while querying for the campaign status.
For status returned description go to Appendix B.

session_id: The session ID returned from authentication

campid: The campaign ID returned by the Gateway when a campaign has been
successfully submitted

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/campstatus.jsp?session_id=xxxxxxxx &campid=xxx

Success Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Camp_Status</command>
−
<data>
−
<recipient>
<msisdn>923451710200</msisdn>
<status>1</status>
</recipient>
−
<recipient>
<msisdn>92345612225</msisdn>
<status>1</status>
</recipient>
−
<recipient>
<msisdn>923439999619</msisdn>
<status>1</status>
</recipient>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Camp_Status</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

9
 8. Ping
This command prevents the session ID from expiring in periods of inactivity. The session ID is set/refresh to
expire after next 30 minutes. The only parameter required for this command is the Session ID.

session_id: The session ID returned from authentication

campid: The campaign ID returned by the Gateway when a campaign has been
successfully submitted

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/ping.jsp?session_id=xxx

Success Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Ping_request</command>
<data>Session ID</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Ping_request</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

10
 9. Sending a Quick Call
This command is used to send a Quick Call. To send a quick call, the destination address should be in the format
923xxxxxxxxx. The basic parameters required are:

session_id: The session ID returned from authentication

to: The campaign ID returned by the Gateway when a campaign has been
successfully submitted
file_id: The ID of audio recording to play on call
max_retries (optional): The number of retries to make if the call attempt is not successful. This
parameter is optional and by default only single call is made. Number of
retries can vary from 0-2

Each call returns a unique identifier in the form of Call ID. For multiple destination numbers, a comma separated
list of Call ID's is returned. Single Call ID for each mobile number. If even a single mobile number is in incorrect
format, the request will be rejected. The Call ID can be used to track and monitor any given call. The Call ID is
returned after each post.

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/makecall.jsp?session_id=xxxx&to=923xxxxxxxxx,923xxxxxxxx
x,923xxxxxxxxx&file_id=xxxx&max_retries=2

Success Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Submit_CALL</command>
<data>Call ID1,Call ID2,Call ID3</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Submit_CALL</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

11
 10. Query a Quick Call

This command returns the status of a quick call. You can query the status with the call_id which is the call ID
returned by a successful quick call submission request. For authentication you need to pass session_id as well
while querying for the call status. For status returned description go to Appendix C

session_id: The session ID returned from authentication

call_id: The call ID returned in response to the Make a Quick Call command.

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/querycall.jsp?session_id=xxx&call_id=xxxx

Success Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Query_Call</command>
<data>
<recipient>
<msisdn>923XXXXXXXXX</msisdn>
<status>STATUS</status>
<recipient>
</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Query_Call</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

12
 11. Get Incoming SMS Information

This command is used to get information related to Incoming messages of current account. For authentication
you have to pass session_id as well. To get information the parameter required are:

session_id: The session ID returned from authentication

response_type (optional): Default response is in XML format if parameter is not included.
Use response_type=2 for JSON format

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/incoming_sms_info.jsp?session_id=xxxx&response_type=1

Success Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>retrieve_incoming_sms_info</command>
<data>
<credit>0.1</credit>
<currentFreeIncomingSmsMessages>0</currentFreeIncomingSmsMessages>
<unpaidPendingMessageCount>1</unpaidPendingMessageCount>
</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>retrieve_incoming_sms_info</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

13
 12. Action on Unpaid Pending Incoming SMS
This command is used to retrieve the pending incoming SMS by paying for them or discarding all pending
incoming messages. Following parameters are used to achieve this:

session_id: The session ID returned from authentication

response_type (optional): Default response is in XML format if parameter is not included.
Use response_type=2 for JSON format
action: Use action=1 to retrieve and pay for all pending SMS
Use action=2 to discard all pending SMS

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/pending_unpaid_sms_action.jsp?session_id=xxxx&response
_type=1

Success Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>pending_unpaid_sms_action</command>
<data>
<credit>0.1</credit>
<currentFreeIncomingSmsMessages>0</currentFreeIncomingSmsMessages>
<unpaidPendingMessageCount>1</unpaidPendingMessageCount>
<discardedMessagesCount>0</discardedMessagesCount>
<successfulChargedEntriesCount>0</successfulChargedEntriesCount>
<successfulChargedSmsCount>0</successfulChargedSmsCount>
</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>pending_unpaid_sms_action</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

14
 13. Fetching Pending Paid Incoming SMS

This command is used to fetch pending incoming SMS. The number of SMS to be fetched in one go can also be
optionally specified. Following parameters are used to achieve this:

session_id: The session ID returned from authentication

response_type (optional): Default response is in XML format if parameter is not included.
Use response_type=2 for JSON format
size (optional): Specifies the number of SMS to be fetched in one go. This should be less
than or equal to the maximum number of pending messages.
If parameter not passed, default number of pending SMS would be
returned.
date (optional): Optional parameter to limit the start date for fetching incoming SMS.
Format: YYYY-MM-DD

Example:

Command:

https://telenorcsms.com.pk:27677/corporate_sms2/api/get_incoming_messages.jsp?session_id=xxxx&size=20&r
esponse_type=1&date=2017-01-01

SuccessResponse:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>get_incoming_messages</command>
<data>
<credit>0.1</credit>
<currentFreeIncomingSmsMessages>0</currentFreeIncomingSmsMessages>
<unpaidPendingMessageCount>1</unpaidPendingMessageCount>
<incomingSms>
<id>1</id>
<message>hi every one</message>
<msisdn>923451234567</msisdn>
<shortCode>123</shortCode>
<timestamp>2017,01,12 18:01</timestamp>
</incomingSms>
<incomingSms>
<id>17</id>
<message>test message</message>
<msisdn>923458590088</msisdn>
<shortCode>123</shortCode>
<timestamp>2017,01,17 18:25</timestamp>
</incomingSms>
</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>get_incoming_messages</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

15
 14. Upload Audio File

This command can be used to upload an Audio File. This is a post-method multipart request and uploads audio
file. Upon completion an ID of file would be returned. The parameters are:

session_id: The session ID returned from authentication

name: The unique name of the Audio File for identification
audio_file: The audio file which is to be uploaded. File format must be .wav and file
size should be equal to or less than 5MB.
Codec: PCM S16 LE (araw)
Channel: Mono
Sample Rate: 8000
Bits per Sample: 16

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/audio_upload.jsp?session_id=xxxx

Success Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Audio_File_Upload</command>
<data>File Id</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Audio_File_Upload</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

16
 15. Check Uploaded Audio File Status
This command can be used to check the status of the uploaded audio, whether it is ready to be used or not. See
Appendix-F for responses. The parameters are:

session_id: The session ID returned from authentication

file_id: The ID of the audio file whose status needs to be checked

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/audio_status.jsp?session_id=xxxx&file_id=xxx

Success Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Audio_File_Status</command>
<data>Status</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Audio_File_Status</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

17
 16. Create a Voice Broadcast Campaign
This command can be used to create broadcast campaign in order to send call to lists of subscribers at specified
time. The basic parameters required are:

session_id: The session ID returned from authentication

name: The name to identify the campaign
group_ids: Comma-separated list of Subscriber List IDs to be used in the campaign
file_id: The ID of the audio file to be played during call
text (optional): SMS Text to be sent in case the recipient does not attend call
max_retries (optional): Number of retries to be made in case a recipient does not attend call.
Default is 0. Max value that can be set is 2
start_date (optional): The date and time at which the campaign will start
Format: YYYY-MM-DD<space>HH:MM:SS, e.g., 2017-01-01 13:01:59
end_date (optional): The date and time at which the campaign will end. If parameter not
passed, a default value of 2 days would be used.
Format: YYYY-MM-DD<space>HH:MM:SS, e.g., 2017-01-01 13:01:59
start_time (optional): Daily start time for the campaign. To be used in case the campaign is to
be executed within a specific time window.
Format: HH:MM, e.g., 13:01
end_time (optional): Daily end time for the campaign. To be used in case the campaign is to
be executed within a specific time window.
Format: HH:MM, e.g., 13:01
response_type (optional): Default response is in XML format if parameter is not included.
Use response_type=2 for JSON format

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/voice_broadcast_campaign.jsp?session_id=xxxx&name=xxxx
&file_id=xxx&group_ids=xxxx&text=xxxx&max_retries=xx&start_date=xxx&end_datexxxx&start_time=xxxx&end_tim
e=xxxx

SuccessResponse:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Create_Voice_Broadcast_CAMP</command>
<data>Campaign ID</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Create_Voice_Broadcast_CAMP</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

18
 17. Create a Voice Feedback Campaign
This command can be used to create a single step Feedback campaign over call. The parameters used are:

session_id: The session ID returned from authentication

name: The name to identify the campaign
group_ids: Comma-separated list of Subscriber List IDs to be used in the campaign
file_id: The ID of the audio file to be played during call. This file should have the
question for which the feedback is required.
valid_options: The maximum number of valid options for the question asked. Min value
0, Max value 9
e.g., if a question has two possible responses (yes,no), valid_options=2
should be used.
text (optional): SMS Text to be sent in case the recipient does not attend call
max_retries (optional): Number of retries to be made in case a recipient does not attend call.
Default is 0. Max value that can be set is 2
start_date (optional): The date and time at which the campaign will start.
Format: YYYY-MM-DD<space>HH:MM:SS, e.g., 2017-01-01 13:01:59
end_date (optional): The date and time at which the campaign will end. If parameter not
passed, a default value of 2 days would be used.
Format: YYYY-MM-DD<space>HH:MM:SS, e.g., 2017-01-01 13:01:59
start_time (optional): Daily start time for the campaign. To be used in case the campaign is to
be executed within a specific time window. Format: HH:MM, e.g., 13:01
end_time (optional): Daily end time for the campaign. To be used in case the campaign is to
be executed within a specific time window. Format: HH:MM, e.g., 13:01
valid_feedback_file_id The ID of the audio file to be played if the feedback provided is in the
(optional): valid range of options. Call will end after this.
invalid_feedback_file_id The ID of the audio to be played if the feedback provided is outside the
(optional): valid range of options. Main question file is played after this.
response_type (optional): Default response is in XML format if parameter is not included.
Use response_type=2 for JSON format

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/voice_feedback_campaign.jsp?session_id=xxxx&name=xxx
x&file_id=xxx&group_ids=xxxx&valid_options=xx&text=xxxx&max_retries=xx&start_date=xxxx&end_date=xxxx&st
art_time=xxxx&end_time=xxxx&valid_feedback_file_id=xx&invalid_feedback_file_id=xx

SuccessResponse:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Create_Voice_Feedback_CAMP</command>
<data>Campaign ID</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Create_Voice_Feedback_CAMP</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

19
 18. Create a Voice Dynamic Campaign
This command can be used to create dynamic voice campaign in order to schedule out-bound calls to the subscriber
lists (containing MSISDNs and Digits) specified. The parameters used are:

session_id: The session ID returned from authentication

name: The name to identify the campaign
group_ids: Comma-separated list of Subscriber List IDs to be used in the campaign
file_id: The ID of the audio file to be played during call. This file should have the
question for which the feedback is required.
language: The language in which the text would be pronounced.
language=1 for English and language=2 for Urdu
digits: Digits can be pronounced as Numerical values (each digit read
individually, 123 as one two three) or monetary values (pronounced
based on their decimal place, 123 as One Hundred and Twenty-Three)
digits=1 for Monetary and digits=2 for Numeric pronunciation
voice: The gender in which the text would be pronounced. voice=1
for Male, voice=2 for Female
text (optional): SMS Text to be sent in case the recipient does not attend call
max_retries (optional): Number of retries to be made in case a recipient does not attend call.
Default is 0. Max value that can be set is 2
start_date (optional): The date and time at which the campaign will start.
Format: YYYY-MM-DD<space>HH:MM:SS, e.g., 2017-01-01 13:01:59
end_date (optional): The date and time at which the campaign will end. If parameter not
passed, a default value of 2 days would be used.
Format: YYYY-MM-DD<space>HH:MM:SS, e.g., 2017-01-01 13:01:59
start_time (optional): Daily start time for the campaign. To be used in case the campaign is to be
executed within a specific time window. Format: HH:MM, e.g., 13:01
end_time (optional): Daily end time for the campaign. To be used in case the campaign is to be
executed within a specific time window. Format: HH:MM, e.g., 13:01
ending_audio_id (optional): The ID of the file, which is to be played at the end of the call
response_type (optional): Default response is in XML format if parameter is not included.
Use response_type=2 for JSON format

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/voice_dynamic_campaign.jsp?session_id=xxxx&name=xxx
x&file_id=xxx&group_ids=xxx&language=xxx&digits=xxx&voice=xxx&text=xxxx&max_retries=xxx&start_date=x
xxx&end_date=xxxx&start_time=xxx&end_time=xxx&ending_audio_id=xxx

SuccessResponse:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Create_Voice_Dynamic_CAMP</command>
<data>Campaign ID</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Create_Voice_Dynamic_CAMP</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>
20
 19. Query a Voice Campaign
This command returns the status of the specified voice campaign. See Appendix-G for responses. The
parameters are:

session_id: The session ID returned from authentication

camp_id: The ID of the Voice Campaign that needs to be checked

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/voice_campaign_status.jsp?session_id=xxxx&camp_id=xxx

Success Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Voice_Camp_Status</command>
<data>
<campaignName>jop</campaignName>
<status>2</status>
<audioClipId>162</audioClipId>
<maxRetries>0</maxRetries>
<smsText/>
<startDate>18 May,2017 12:28PM</startDate>
<endDate>19 May,2017 12:28PM</endDate>
<startTime>0:0</startTime>
<endTime>23:59</endTime>
<callAttemps>0</callAttemps>
<answered>0</answered>
<notAnswered>0</notAnswered>
<notResponding>0</notResponding>
<busy>0</busy>
<campaignCost>0.0</campaignCost>
<language>1</language>
<pronunciationType>2</pronunciationType>
<voice>1</voice>
</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Voice_Camp_Status</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

21
 20. Query a Voice Campaign Status
This command returns the status of the specified voice campaign. See Appendix-G for responses. The
parameters are:

session_id: The session ID returned from authentication

camp_id: The ID of the Voice Campaign that needs to be checked

offset: Number of records to be skipped. 0 means fetch records

from the start

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/queryvoicecampaignstatus.jsp?session_id=xxxx&campid=xxx
&offset=0

Success Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Voice_Camp_Subscriber_Status</command>
<data>
<campaignId>xxx</campaignId>
−
<recipient>
<callDuration>15</callDuration>
<msisdn>923458590049</msisdn>
<status>2</status>
</recipient>
−
<recipient>
<callDuration>30</callDuration>
<msisdn>923458590048</msisdn>
<status>2</status>
</recipient>
−
<totalRecords>2</totalRecords>
</data>
<response>OK</response>
</corpsms>

Error Response:
<corpsms>
<command>Voice_Camp_Subscriber_Status</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command> Voice_Camp_Subscriber_Status </command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

22
 21. Create feedback call
This command is used to send a Feedback Quick Call. To send a quick call, the destination address should be in
the format 923xxxxxxxxx. The basic parameters required are:

session_id: The session ID returned from authentication.

to: The campaign ID returned by the Gateway when a campaign has been
successfully submitted.
file_id: The ID of audio recording to play on call
max_retries (optional): The number of retries to make if the call attempt is not successful. This
parameter is optional and by default only single call is made. Number of
retries can vary from 0-2.
valid_options: The valid options required for feedback call.
valid_feedback_file_id: The ID of audio to be played after valid feedback.
invalid_feedback_file_id: The ID of audio to be played after invalid feedback.

Each call returns a unique identifier in the form of Call ID. For multiple destination numbers, a comma separated
list of Call ID's is returned. Single Call ID for each mobile number. If even a single mobile number is in incorrect
format, the request will be rejected. The Call ID can be used to track and monitor any given call. The Call ID is
returned after each post.

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/make_feedback_call.jsp?session_id=xxxx&to=923xxxxxxxxx,9
23xxxxxxxxx,923xxxxxxxxx&file_id=xxxx&max_retries=2&valid_options=5&valid_feedback_file_id=xxx&invalid_feedba
ck_file_id=xxx

Success Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Create Feeback Quick Call</command>
<data>Call ID1,Call ID2,Call ID3</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>Create Feeback Quick Call</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

23
 22. Balance Inquiry
This command can be used to check the Remaining Credit of account. The parameters are:

session_id: The session ID returned from authentication

Example:

Command:
https://telenorcsms.com.pk:27677/corporate_sms2/api/balanceInquiry.jsp?session_id=xxxx

Success Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>balanceInquiry</command>
<data>Credit Remaining</data>
<response>OK</response>
</corpsms>

Error Response:
<?xml version="1.0" encoding="UTF-8"?>
<corpsms>
<command>balanceInquiry</command>
<data>Error Code</data>
<response>ERROR</response>
</corpsms>

24
 23. Appendix - A

Error Codes

Codes Translation
200 Failed login. Username and password do not match
201 Unknown MSISDN, Please Check Format i.e. 92345xxxxxxx
100 Out of credit.
101 Field or input parameter missing
102 Invalid session ID or the session has expired. Login again.
103 Invalid Mask
104 Invalid operator ID
204 Sub user permission not allowed
211 Unknown Message ID
300 Account has been blocked/suspended
400 Duplicate list name.
401 List name is missing.
411 Invalid MSISDN in the list.
412 List ID is missing.
413 No MSISDNs in the list.
414 List could not be updated. Unknown error.
415 Invalid List ID.
500 Duplicate campaign name.
501 Campaign name is missing.
502 SMS text is missing.
503 No list selected or one of the list IDs is invalid.
504 Invalid schedule time for campaign.
506 Cannot send message at the specified time. Please specify a different time.
507 Campaign could not be saved. Unknown Error.
600 Campaign ID is missing
700 File ID is missing
701 File not available or not ready
702 Invalid value for max retries
703 Invalid value for Call ID
704 Invalid Mask for IVR
301 Incoming SMS feature is not available for current user
302 In valid action attribute value
303 User has entered date and is not valid date
304 API throughput limit reached for TPS Control mode
305 User SMS/recipients exceeds than allowed throughput
306 Number of campaigns exceeds then the allowed limit that can be scheduled
from an account in a day.

25
 24. Appendix - B

Message Status

Value Status
0 Not Sent
1 Sent

26
 25. Appendix - C

Call Status

Codes Translation
0 Call Scheduled
1 Call Sent
2 Recipient Busy
3 Not Responding
4 Not Answering

27
 26. Appendix - D

Operator IDs for Quick Message

ID Operator
1 Telenor
2 Jazz
3 Zong
4 Warid
5 Ufone

28
 27. Appendix - E

Voice Campaign

Code Translation
402 Invalid list name
508 Invalid start time for voice campaign
509 Invalid end time for voice campaign
510 Invalid end Date in campaign
511 Invalid campaign name
512 Message Text for voice campaign length greater than allowed length
601 Invalid campaign ID for voice campaign
602 Filename missing for audio upload
603 Invalid audio File name already exists
604 Invalid request File not uploaded
605 Audio File larger than size allowed
606 Invalid File Encoding
607 Invalid file audio channels
608 Invalid file audio sample rate
609 Invalid file audio bit rate
610 File not uploaded unknown error
611 Invalid File extension
612 Invalid recording name
705 DTMF valid options not provided or invalid
706 File not available or not ready to be used for valid feedback option
707 File not available or not ready to be used for Invalid feedback option
708 Dynamic Campaign language option missing or invalid
709 Dynamic Campaign pronunciation option missing or invalid
710 Dynamic Campaign voice gender option missing or invalid
File not available or not ready to be used for Ending recording in Dynamic
711
IVR
712 Invalid Audio File ID
713 Audio File not ready

29
 28. Appendix - F

Audio File Upload Status

Code Translation
0 Audio File Not Ready
1 Audio File Ready

30
 29. Appendix - G

Voice Campaign Query Status

Code Translation
0 Unapproved Voice Campaign Status
1 Scheduled Voice Campaign Status
2 Testing Voice Campaign Status
3 Sent to some users Campaign Status
4 Sent Voice Campaign Status
5 Configuring Voice Campaign Status
6 Configuring Voice Campaign Status
7 Configuring Voice Campaign Status
8 Sending Voice Campaign Status
10 Pending for moderator approval Voice Campaign Status
12 Rejected by moderator Voice Campaign Status
13 Unknown Voice Campaign Status
14 Expired

31