Voice API with SIP routing and carrier registration
Continuing discussion of Voice telephony API. Setting up carriers with SIP-specific attributes.
In previous API post we discussed how to send automated voice call and play prerecorded or text to speech messages to multiple recipients at once and get results report. Now we will discuss how to set some more advanced SIP attributes in case they are required.
Let's start with setting some default parameters by carrier. In our sample case we will have Carrier1 which should be set with following attributes:
- Hostname: sip.carrier1.com
- Prefix: 8888
- Codecs accepted: G711 ulaw and alaw
- Registration not required
And Carrier2 with these attributes:
- IP address: 10.2.2.22
- Prefix: None
- Codecs accepted: G711 ulaw and alaw, G.729 and G.723
- Registration required.
- Registration username: client1
- Registration password: password1
Here is the request to set up carrier1:
POST /carriers
{
"name" : "carrier 1",
"host" : "sip.carrier1.com",
"protocol" : "SIP",
"prefix" : "8888",
"codecs" : ["mulaw", "alaw"],
"register" : false
}
Response will be like:
{
"code": 0,
"status": 200,
"data": "accepted",
"request_id": "63afc352-21ce-4a42-8b70-7ed8f994d5b7",
"carrier_id": "d49d1f1e"
}
As this carrier does not require registration, there is no action taken on the SIP level, so we do not need to have any further action.
Setting up Carrier2 now:
POST /carriers
{
"name" : "carrier 2",
"host" : "10.2.2.2",
"protocol" : "SIP",
"codecs" : ["mulaw", "alaw", "g729", "g723"],
"register" : true,
"username" : "client1",
}
Response:
{
"code": 0,
"status": 200,
"data": "accepted",
"request_id": "ddb8cefc-e310-4784-b8ac-aacfb1b79f1d",
"carrier_id": "74445609"
}
This carrier requires registration. We may want to check if the registration was successful or not. We will take carrier ID from the system and check if registration succeeded.
GET /status/carrier/74445609
will respond:
{
"code": 0,
"status": 200,
"data": "accepted",
"request_id": "ddb8cefc-e310-4784-b8ac-aacfb1b79f1d",
"result" : {
"sip_registration": "registered"
}
}
We can and perhaps should perform this action on the regular basis if we want to be sure that SIP registration still exists.
Now, when we have several carriers set up, our call requests become a bit simpler. Instead of full SIP URL in the destination field, we can just send called party number (numerical part only) and the system will create proper SIP URI before making SIP call. We should include Carrier ID returned to us in carrier setup API calls.
POST /voice/call/play
{
"to": "123456",
"from": "me",
"playlist":
[
{ "play": "http://server.domain.com/voices/hello.wav"
},
{
"play": "http://server.domain.com/voices/main-message.wav"
},
{
"play": "http://server.domain.com/voices/goodbye-thanks.wav"
}
]
"carrier_id" : "74445609"
}
Therefore we have now functional routing set up, we are able to send calls to the carrier of our choice. Next we will discuss how to offload decision of routing from our application and set up more advanced routing scenario.
