×

Overview

To seamlessly onboard customers using your platform, you can integrate our API endpoint for creating WhatsApp onboarding links. This API enables Independent Software Vendors (ISVs) and customers to integrate the onboarding process into their portals, allowing a streamlined experience for their partners.

Endpoint

To obtain tokens and URL details through the Exotel API, initiate an HTTP POST request to the specified endpoint.

POST

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/isv

  • Replace <your_api_key> and <your_api_token> with your API key and token.
  • Replace <your_sid> with your Account SID.
  • Replace <subdomain> with the region of your account. For the Singapore cluster, use @api.exotel.com, and for the Mumbai cluster, use @api.in.exotel.com.

Usage

Upon hitting the API endpoint, a link will be generated and provided in the API response. When this link is opened in a separate tab, the following flow will be initiated:

  • A page opens with WhatsApp API details, a Facebook Business Manager (FB BM) account creation link, a video demonstrating embedded onboarding, and a "Login with Facebook" button.
  • Clicking on the "Login with Facebook" button opens a pop-up, and the background page is highlighted to indicate the pop-up.
  • The normal embedded flow continues within the pop-up.
  • Upon successful onboarding, closing the pop-up also closes the page.

Key Points to Remember

  • Link Validity: URLs fetched using the API are valid for 24 hours, allowing them to be used within this timeframe for onboarding new customers.
  • Number of URLs: You can fetch up to 50 URLs at a time, facilitating the onboarding process for multiple customers simultaneously.
  • Customer Onboarding Limit: A single token can successfully onboard up to five different customers within the 24-hour timeframe.

These restrictions ensure the security and controlled usage of fetched tokens, promoting efficient customer onboarding for your business.

POST parameters

Parameter Name Parameter Type Mandatory/Optional Value
whatsapp ChannelObject Optional Information related to the whatsapp

Channel Object

Parameter Name Parameter Type Mandatory/Optional Value
isv IsvObject Mandatory The url with the token will be shown

Isv Object

Parameter Name Parameter Type Mandatory/Optional Value
Url String Mandatory The url along with the token is generated

Please refer Exotel's sample postman collection to try out the APIs, we have also shared some examples here for your reference.

  • Example Request of Creating Onboarding Link
curl --location --globoff --request POST 'https://{{AuthKey}}:{{AuthToken}}@{{SubDomain}}/v2/accounts/{{AccountSid}}/isv' \
--header 'Content-Type: text/plain'
  • Example Response of Creating Onboarding Link
{
    "request_id": "15dbef467ff34a96b78e67baf63c19bf",
    "method": "GET",
    "http_code": 200,
    "response": {
        "whatsapp": {
            "isv": {
                "code": 200,
                "error_data": null,
                "status": "success",
                "data": {
                    "onboarding_token_status": "VALID"
                }
            }
        }
    }
}

 

HTTP Error Codes

HTTP Error Codes

Error Message

202

Accepted - Request accepted.

400

Bad Request - Something in your header or request body was malformed/missing.

More than 100 messages specified in a request

401

Unauthorized - Necessary credentials were either missing or invalid.

402

Payment Required - The action is not available on your plan, or you have exceeded usage limits for your current plan.

403

Your credentials are valid, but you don’t have access to the requested resource.

404

Not Found - The object you’re requesting doesn’t exist.

5xx

Server Errors - Something went wrong at our end. Please try again.

Validate Token

Parameter Name

Parameter Type

Mandatory/Optional

Value

access_token

String

Mandatory

UUID token which has been generated along with the base URL.

 

GET - Validate Token API

You can copy the UUID which is generated in the Onboarding Base URL and provide it in the Get Validate Token API in the end and check then validity.

Example -

  • If this is the onboarding link that is generated - "onboarding_url": "https://messaging.exotel.com/ua-links/isv-onboard/41eabcd-abcdabcd"  then you can copy the last part of the URL like "41eabcd-abcdabcd".
  • Open the Get - Validate Token API and provide the copied token in the end of the URL. 
  • The Sample URL with the above example will look like this - 'https://{{AuthKey}}:{{AuthToken}}@{{SubDomain}}/v2/accounts/{{AccountSid}}/isv?access_token=41eabcd-abcdabcd'
GET

https://{{AuthKey}}:{{AuthToken}}@{{SubDomain}}/v2/accounts/{{AccountSid}}/isv?access_token={{token}}

  • Example Response of Validate Token API
{
    "request_id": "15dbef467ff34a96b78e67baf63c19bf",
    "method": "GET",
    "http_code": 200,
    "response": {
        "whatsapp": {
            "isv": {
                "code": 200,
                "error_data": null,
                "status": "success",
                "data": {
                    "onboarding_token_status": "VALID"
                }
            }
        }
    }
}