Platform Integration

13 min

Platform Integration

Customer API Endpoints

Exotel provides full control to customers to implement call routing business logic. For this, customers need to host the following HTTP endpoints to handle callbacks from Exotel platform.

Dial Whom Endpoint

Host a HTTP endpoint which will be queried by the Exotel platform to get to the destination user.

Method: GET

Request URL (Example): https://company.com/v1/accounts/exotel/dialtonumber

Note: This URL needs to be provided to Exotel or configured in the connect applet.

Request Body:

CallSid - unique call identifier

CallFrom - caller username

CallTo - exophone

CustomField - It will be passed only if you have sent the second optional param while making the call from the app.

Expected Response:

On success, the API should return with response code 200 OK. The response body should be a string of type sip:<remoteId>. “sip:” tag is needed to hint the exotel platform to connect calls over voip. At present, SIP and PSTN intermixing is not supported. Any other response is treated as failure. remoteId is the username with which the call destination subscriber was registered with Exotel platform.

Example:

Request

GET /v1/accounts/exotelip2ipcalling1/dialtonumber?CallSid=743ddcf5a0552050bc37b6d0ff9613bn&CallFrom=sip:Alice&CallTo=sip:08040408080&CallStatus=ringing&Direction=incoming&Created=Sat,+23+Nov+2019+22:00:37&DialCallDuration=0&StartTime=2019-11-23+22:00:37&EndTime=1970-01-01+05:30:00&CallType=call-attempt&DialWhomNumber=&flow_id=249196&tenant_id=113828&From=sip:Alice&To=sip:08040408080&CurrentTime=2019-11-23+22:00:37

Response

{ "fetch_after_attempt": false, "destination": { "numbers": [ "sip:1234567890" ] }, "outgoing_phone_number": "08080808080", "record": false, "recording_channels": "dual", "max_ringing_duration": 30, "max_conversation_duration": 3600, "request_id": "2e48100e6b474714b1a64bfa9f5b7a55", "method": "GET", "http_code": 200, "code": null, "error_data": null, "status": null }

Push Notification Endpoint

Exotel implements registration-less dialing where a user need not periodically register with SIP registrar for receiving incoming calls. Instead the call details are pushed to the device as push notification using which call can be established. This method is beneficial as calls will reach the user even when the app is not in foreground or swipe killed. It saves battery since it does not need to keep persistent voip connection when idle.

Exotel will provide call data as payload & payloadVersion to your push notification endpoint that needs to be pushed to the client device from your application backend.

Refer section Receive Incoming Call for handling of push notification payload.

Note - Headers are not supported in the notify endpoints.

Method: POST

Request URL (Example): https://<your_api_key>:<your_api_token>@company.com/v1/accounts/exotel/pushtoclient

Note: This URL needs to be configured in Exotel platform

Request Body:

subscriberName - Name with which subscriber registered with Exotel platform

payload - call data which should be passed to the client SDK

payloadVersion - version of payload scheme

Expected Response:

On success, the API should return with response code 200 OK. Any other response is treated as failure.

Exotel API Endpoints

Subscriber Management

Customers can manage their subscribers in the Exotel platform using the APIs listed “Subscriber-Management-API” document.

For clients to be able to use voip calling features they need to be added as subscribers under your account. There are two ways in which your client registration with Exotel account happens,

Pre-provisioning

The customer pre-configures the client accounts even before the app is installed by the client. Refer to the “Subscriber-Management-API” document for details on creating client accounts.

Dynamic provisioning

A client account is created after the app is installed by the user and signs-up with the application backend. Refer to Authentication and Authorization for workflow details. Once client provisioning happens, clients can be managed using Subscriber Management APIs.

Authentication and Authorization

Access to the exotel platform by ExotelVoice is authenticated using a set of bearer tokens - subscriber_token. The Application backend must obtain these tokens from the exotel platform and provide them to the client on request. Refer to the “Subscriber-Management-API” document for details.

On receiving the onAuthenticationFailure event, the application should request a new subscriber_token from its backend and reinitialize the SDK as shown in section Initialize Library. Contact exotel support if you get onAuthenticationFailure even after token renewal.

onAuthenticationError() event provides following error types:

AUTHENTICATION_INVALID_TOKEN - token parameters are invalid

AUTHENTICATION_EXPIRED_TOKEN - token expired

Reference Documents

Android JavaDoc for the ExotelVoice library API

Subscriber-Management-API document for details on API to manage subscriber

Support Contact

Please write to [email protected] for any support required with integration.

Troubleshooting Guide

Outgoing Call

I am not getting any requests on the “Dial Whom” endpoint for outgoing calls?

Check if “Dial Whom” URL was configured in Connect Applet and reachable. Check if the call is listed in your account dashboard. If not, then Check if the phone has internet connectivity. Check if the SIP Exophone number was set in CallController::dial() API. Check if CallListener::onCallFailed() event was received with error type CONGESTION_ERROR, which means rate limit quota was exceeded. Check if CallListener::onCallInitiated() event was received from the SDK. Check if Call::getCallDetails() returns non-null sessionId field Check if Report the issue to exotel support with sessionId (from App) and Call-Reference-Id (if available, from account dashboard)

I am hearing a ringing tone but the callee has not received the call?

Ringing tone implies that the call has reached the exotel platform.

Incoming Call

My calls are not landing on the callee app?

Check if the call is listed in your account dashboard and dialout happened to the remote subscriber. If not then, refer to the troubleshooting guide for outgoing calls. Check if the application received push notification with call payload from your application backend. If not, then Check the device OEM. If Xiaomi phones, refer to section Problems with push notifications on Xiaomi devices. Check if Push Notification URL is reachable and configured in the exotel platform. Check if Push Notification URL got the call payload from exotel platform. Check if the call payload was sent to the target device from your backend. If the call notification is received in the app, then Check if the library is initialized using ExotelVoiceClient::isInitialized() Check if payload received in push notification was programmed in the library through ExotelVoiceClient::relaySessionData() Report the issue to exotel support with Call-Reference-Id (from account dashboard)

Problems with push notifications on Xiaomi devices

Your application needs to have the following additional permissions in the MIUI settings page. Open settings (by tapping the cog icon in the top right corner), select “Manage Apps”, select “your application” Enable “Autostart” Select “Other permissions” Turn on “Show on Lock Screen” Turn on “Display pop-up windows while running in the background” Select “Battery Saver” and set “No restrictions” The steps here refer to MIUI Global 11.0.2 on Android 7.1. Depending on device and software version, designation and location of menu items may differ.

Ringtone not playing while receiving push notifications on Xiaomi devices

Your application needs to have the following additional permissions in the MIUI settings page. Open settings (by tapping the cog icon in the top right corner), select “Manage Apps”, select “your application”. Go to “Notifications” → “Notification Categories” Enable “Allow floating notification” for ‘Exotel Voip Sample’ Enable “Allow floating notification” for ‘io.cloudonix.sdk.ForegroundNotificationChannelName’ The steps here refer to MIUI Global 13.0.7.0 on Android 12.016. Depending on device and software version, designation and location of menu items may differ.

Display Not Awake

Display awake is handled from the following permission defined in manifest: <uses-permission android:name="android.permission.WAKE_LOCK" /> It has been found that the ringtone is playing but the display is not awake, the above permission can’t handle it properly. This can be handled from the application side using PowerManager implementation Light up screen when notification received android which is not handled in current app code.

Authentication

Requesting subscriber-token from exotel platform giving 4xx response?

Response Code	Troubleshooting
400	Malformed packet. Check subscriber_name format. It should be an alphanumeric string of size less than 16 characters.
401	It requires basic authentication using API key:token
403	VoIP calling is not enabled in your account. Contact exotel support.

Why is SDK reporting onAuthenticationFailure response for a subscriber token received from exotel platform?

Check the ErrorType in response. If it is,
AUTHENTICATION_INVALID_TOKEN Invalid Token. Initialize new token
AUTHENTICATION_EXPIRED_TOKEN Token expired. Initialize new token
Contact Exotel support if the issue persists.