Call 8886599559 for Indian queries, 971-501561627 (UAE) for Middle East, 852-60262470 for Hong kong (or)
Email to: contactus@smscountry.com
Download PDF

BASIC REQUEST/RESPONSE FORMAT


     URL : http://voiceapi.smscountry.com/api 
     API Request Parameters from Client
api_key = user_api_key
access_key = user_access_key
xml = <request action="www.yourdomain.com/callback" method="POST">
              <from> </from>
              <to> </to>
          </request>
     API Response Parameters from Server
{
  smscresponse:
      {
          calluid: "36e9d483-ebac-47fe-83a3-3a78af828923"
      }
 } 
Note:
  1. user_api_key, user_access_key will be provided by us.
  2. Response will be in Json or Query String parameters depending on the method requested.
    • If method="POST" response will be in Json.
    • if method="GET" response will be in Query String parameters.

REQUEST


     Request Root Tag :
     When you make an API call to the voice platform, all the other tags should be under this root tag     
<request action="www.yourdomain.com/callback" method=”GET” >
        <to> 9866955337 </to>
        <play> www.yourdomainname.com/myfavclip.mp3 </play>
</request> 
      
Request Root Tag Attributes / Tags are as follows :
Attributes/TagsDescription
action Call back url where you want the in call events to be notified (OPTIONAL).
method http request method to be used for the call back. GET or POST (OPTIONAL, Default is GET).
<from> Optional tag for mentioning the FROM DID (number) from which the voice call to be originated. You can mention this only if you have subscribed for a dedicated DID (phone number) in your account.
<to> Comma separated list of destination numbers. Ex : 9866955337, 04030990500
<play> To play a recorded voice clip of .mp3, .wav & .au format. <play> www.urdomainname.com/recordedclip.mp3 </play>
<speak> To speak out the text as speech in a default female voice. <speak> This message will be converted to speech </speak>

SMSCRESPONSE


     Response Root Tag :
     For each api request you make to the voice platform you get an response back to call back url you have
mentioned (www.yourdomain.com/callback).  
     If the response is requested in GET method :
    smscresponse[calluid] = 36e9d483-ebac-47fe-83a3-3a78af828948
    smscresponse[to] = 9866955337
    smscresponse[callstatus] = received
    smscresponse[event] = newcall
    smscresponse[direction] = outbound
     If the response is requested in POST method :
{
  smscresponse:
    {
        "calluid" : "36e9d483-ebac-47fe-83a3-3a78af828955",
        "to" : "9866955337",
        "callstatus" : "received",
        "event" : "newcall",
        "direction" : "outbound"
    }
}
      
Response Root Tag Attributes / Tags are as follows :
Attributes/TagsDescription
calluid Unique reference id for each request.
to The number dialed in this request.
call Status The status of the call. Any one of the below received inprogress completed
event The event which resulted in this response. Any one of the below newcall record getkeys hangup error
direction Direction of the voice call. Any one of the below outbound (from your system to voice platform) inbound (from voice platform to your system)
error_reason List of error reasons when the event is error "'xml' field should not be empty" "'xml' field is missing" "'api_key' field is missing" "'api_key' should not be empty" "'access_key' field is missing" "'access_key' should not be empty" "invalid 'api_key'" "invalid combination of 'api_key' and 'access_key'" "low balance" "'action' field is missing"
Note:
  1. If you have mentioned more than one number in tag of your request. You will receive multiple call backs for each number with same calluid containing the callstatus of each number respectively.
  2. Based on the optional tags used in the request, the response parameters will change.

EVENT TAGS (Optional)


     All the Event tags will trigger a callback to your url mentioned. You can also mention custom url for each 
     tag if required.
     <record>
     To record your customer voice use this tag as one of the tags in the request xml mentioned above.
<record action="http://www.yourdomain.com/recordclip.aspx" method="get/post" maxlength="30"
fileformat=".wav" finishonkey="#">
</record>
      
Record tag Attributes are as follows :
Attributes/TagsDescription
maxlength Maximum number of seconds you want to record the voice. Default value is 30 secs, if you want more time, mention the value in seconds.
fileformat The file format in which the recorded voice is stored. .wav & .mp3 are supported.
finishonkey Terminator key, the key which customer has to press to inform that he is done with recording..

      Response from the server can be like below:
{
  smscresponse:
    {
        "calluid" : "36e9d483-ebac-47fe-83a3-3a78af828968",
        "to" : "9866955337",
        "event" : "record",
        "callstatus" : "inprogress",
        "recordurl" : "http://voice.smscountry.com/recorded.mp3",
        "duration" : "30",
        "direction" : "outbound"
    }
}
      
Record tag Response attributes are as follows :
Attributes/TagsDescription
recordurl This url will give you the recorded clip out of this action.
duration Recorded message duration in seconds.
Note:
  1. Each voice call can span over multiple request / response communication between voice platform and your domain platform.

     <getkeys>
     To collect customer input from phone keypad (DTMF keys) use this tag as one of the tags in the request
xml mentioned above.<getkeys validkeys=”0123456789” tkey=”#” timeout=”10”>
    <speak>Please enter your customer number followed by # key </speak>
    <timeout type=”play”>www.yourdomain.com/timoutaudio.mp3</timeout>
</getkeys>
      
getkeys Attributes are as follows :
Attributes/TagsDescription
validkeys The keys which the customer should click. you can restrict user to click only 0,1,2 by mentioning validkeys as “012”.
tkey Teriminator key, the key customer has to click to notify that at the end of key presses.
timeout The maximum time platform will wait for user to input DTMF key press. default is 10

      Response from the server can be as below:
{
  smscresponse:
    {
        "calluid" : "36e9d483-ebac-47fe-83a3-3a78af828911",
        "to" : "9866955337",
        "event" : "getkeys",
        "callstatus" : "inprogress",
        "digits" : "3",
        "direction" : "outbound"
    }
}
      
getkeys tag Response attributes are as follows :
Attributes/TagsDescription
digits The digits customer has entered on the phone keypad.

     <hangup>
     To disconnect the call.<hangup/>
{
  smscresponse:
    {
        "calluid" : "36e9d483-ebac-47fe-83a3-3a78af828975",
        "to" : "9866955337",
        "event" : "hangup",
        "callstatus" : "completed",
        "direction" : "outbound"
        "starttime" : "UnixTimeStamp"
        "endtime" : "UnixTimeStamp""
    }
}
      
hangup tag Response attributes are as follows :
Attributes/TagsDescription
starttime Voice call started time (voice platform server time).
endtime Voice call end time (voice platform server time).

     <timeout>     <timeout count=2 type=’play’>
     http://www.yourdomain.com/1.mp3
</timeout>

ADVANCED NOTES (Example of a Call flow)

During the duration of a voice call, there can be multiple request/response between the voice platform and your server. For example:
Step 1

      You issue a call request to a number ask the user some options
<request>
    <from> 9866955337 </from>
    <speak> Welcome to mydomain <speak>
    <getkeys validkeys=”0123456789” tkey=”#”>
        <speak> Please enter your customer number followed by # key </speak>
    </getkeys>
</request>
      
Step 2

      At this stage, the server will collect the user input and gives you a call back with the response.
      Assume that user has entered 42356 as his customer number. Meanwhile the customer is on call hold
{
  smscresponse:
    {
        "calluid" : "36e9d483-ebac-47fe-83a3-3a78af828934",
        "to" : "9866955337",
        "event" : "getkeys",
        "callstatus" : "inprogress",
        "digits" : "42356",
        "direction" : "outbound"
    }
}
      
Step 3

      Now you can lookup in your db about the customer and send the voice platform further instructions
      on how to proceed further. Suppose you want to speak out his balance, thank him and disconnect in 
      the url call back http response mention the xml as
<eventresponse>
    <speak> Welcome to mydomain <speak>
    <hangup/>
</eventresponse>
      
For the instruction after call back, the root tag will be <eventresponse>
Step 4

      At this stage, since the voice platform has received a speak and hangup instruction. It will retreive
      the call in the hold to active state, speak the text mentioned and hang up the call
      Response to the call back url will be
{
  smscresponse:
    {
        "calluid" : "36e9d483-ebac-47fe-83a3-3a78af828934",
        "to" : "9866955337",
        "event" : "hangup",
        "callstatus" : "completed",
        "direction" : "outbound"
        "starttime" : "UnixTimeStamp"
        "endtime" : "UnixTimeStamp"
    }
}
      

Contact Us

  • Telephone : 8886599559
Facebook Twitter LinkedIn Google Plus