--- title: Platform Integration slug: voice-apis/platform-integration docTags: createdAt: 2025-10-03T04:08:34.122Z --- ## 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:\*. “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://:@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. ![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/0zGpoikCUqIq50O6MdQ_x_.blob) 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 *hello\@exotel.in* for any support required with integration. ## Troubleshooting Guide Outgoing Call I am not getting any requests on the “Dial Whom” endpoint for outgoing calls? | 1. Check if *“Dial Whom”* URL was configured in **Connect Applet** and reachable. 2. 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 C*allListener\::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  3. 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? | 1. 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. 2. 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.  3. 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()* 4. Report the issue to **exotel support** with *Call-Reference-Id *(from account dashboard)  | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | Problems with push notifications on Xiaomi devices | 1. 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: 
\

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](https://hello@exotel.com) if the issue persists. |