Custom REST API Call-Back Requests

By using Fonolo’s REST API, you can create your own customized ways for your Clients to request a call-back. Whether this is via a chat-bot, your own custom widget or any other channel, Fonolo’s REST API gives you the flexibility to make call-backs work for you. Your company would already know the SID of the Call-Back Profile.

Below is an example of the order that API calls might take place in, and the data that is used/exchanged in each step.

1. Create the Call-Back Profile and API Application

First, start by creating an API Application within the Fonolo Portal. More information on this can be found HERE. This is required in order to set up authentication with the Fonolo API. More information on authentication with the Fonolo REST API can be found HERE.

Next, an API Call-Back Profile must be set up within the Fonolo Portal. More information can be found on this HERE. Any Call-Back Profile can be used to start/manage calls via the API, however, creating a dedicated Profile allows further customization and dedicated reporting capabilities. After creating the Call-Back Profile, you are provided the Profile’s SID that will be used to query via the API.

2. Query for Call-Back Profile Information

A GET request can be made to pull details on the Call-Back Profile for functionality and features that you have set up for it. Here, you would use the Call-Back Profile SID from the Fonolo Portal. More information on this step can be found HERE.

Some of the relevant data returned includes:

• Status – To see if the Call-Back Profile is active or has been paused in the Fonolo Portal.
• Total Options – To see how many Call Options are on the Profile.
• SMS – If SMS is enabled, you can offer the Client to receive SMS Updates (if configured within Fonolo Portal) (true/false).
• Pre-Call Questions – This will query if Pre-Call Questions are enabled (true/false).
• Scheduled Call-Backs – This will query if Scheduled Call-Backs are enabled (true/false).

3. Query for Features (If Applicable)

Based on previous query, if Pre-Call Questions/SMS Updates/Scheduled Call-Backs returned a “true”, you can make a GET request for this data.

• Pre-Call Questions – Will return a list of questions and answer requirements you can present to Client.
  GET

  https://api.fonolo.com/3.0/profile/[PROFILE_SID]/questions

  More information this step can be found HERE.
• Scheduled Call-Backs – Will return a list of scheduling options you can present to Client.
  GET

  https://api.fonolo.com/3.0/profile/[PROFILE_SID]/scheduling

  More information on this step can be found HERE.
• SMS Options – No other request is required here. If sms=true, you can present a check-box to Client for opting into SMS Updates. If sms=false, you should not present the check-box to the Client.

4. Query for Call Options (List of Queues)

When a Client opens up the widget, GET call made to Fonolo to pull the list of Call Options with data. More information on this step can be found HERE.

Some of the returned data includes:

• Call Option SID – ID of this option.
• Option Name – Display label for Option (the Client will see this).
• Order Position – Position of Option in list order.
• Status – Active, Paused or Closed.

5. Client Selects Preferred Call Option

Next the Client selects their preferred queue from the list of returned options. If the Call Option (queue) that was returned as status=active, then the Client is directed to the next step to enter their phone number. If status=closed or status=paused was returned, you can request Client to pick another option or present a “We apologize, this queue is currently closed” message (or something similar).

6. Client Enters Phone Number and Other Info

When the Client selects their Call Option, they are directed to the next step where they will enter their phone number. If any other options are available (answer a Pre-Call Question, choose a Schedule, or opt in for SMS Updates), these fields should be presented here to gather the data.

7. Initiate the Call-Back

When Client finally presses the button to initiate the call-back process, a POST request is made at this time to submit call-back request to Fonolo. Fonolo will respond with a Call-ID for that call. More information on this step can be found HERE.

• Your POST call to Fonolo MUST include phone number and Call Option SID.
• Optionally, your POST call can include SMS opt-in confirmation, Start Date (if Scheduling is chosen), any pre-call question answers.
• Fonolo will respond with the SID of the call-back, and a URL that you can use to poll for Status of the Call-Back.

8. Poll for Call-Back Status

While Fonolo is processing the call-back (waiting on hold, etc), status update query can be made to update the Client who may be waiting. This is made with a GET request to Fonolo using the Call ID (returned to you in step 7). More information on this step can be found HERE.

This will include information such as:

• Call-Back SID
• Current Status
• Current Duration Timer You can present this data to the Client who may be waiting for their call-back.

9. Cancel A Call-Back

You can also give the Client the option to Cancel an immediate or a Scheduled call-back. This is made with a POST request to Fonolo that includes the Call ID (returned to you in step 7). More information on this step can be found HERE.

10. Response Codes

Every request to the Fonolo API, will return both a status integer, which will always be either 200 on success, or 500 on failure, as well as a message string, which will include a descriptive message of the status.

For example:

{ “status”: 200, “message”: “Call-back started successfully.” }
on success, or;

{ “status”: 500, “message”: “Unable to started call-back. Please try again.” }
on failure.