Add an API Request to your call flow

How to implement the API request action in a call flow.

The API Request action allows you to dynamically route calls within your call flow by sending webhook requests to your own API and letting it respond with instructions for how to direct the call.

How it works

When a call reaches this action in your call flow, Telzio automatically sends a webhook request to a URL specified by you. Your API must then reply with some XML which includes instructions of which direction the call should be sent.

You can choose to continue the call within the same call flow, or transfer it to another Call Flow, user or group of users.

Example:

  1. The call reaches the API Request action in the Call Flow
  2. Telzio sends a webhook to your API
  3. Your API responds with some TelzioML containing instructions for how to process the call
  4. The call continues in the call flow or is transfered according to your API response

API Request Settings

There is no limit to the number of API Requests you can add to your call flow.

Your callers will hear silence from the time the call reaches the API Request action until a response is received from your API.

This means, if your API takes 3 seconds to respond to the webhook sent by Telzio, and you put 5 API Request actions after each other, the caller will hear nothing for 15 seconds.

For that reason, we suggest inserting Announcement actions between your API Request actions, to let the caller know the request is being processed, so they don't hang up.

Request URL

Insert the full URL to the API you want Telzio to send the webhooks to. You can add querystring parameters as needed.

Request Timeout

Specify the max duration you will allow Telzio to wait for a response from your API. The max timeout allowed is 10 seconds.

The call will proceed to the No Answer leg under your action once the Request Timeout has been exceeded.

Authentication Type

You can specify which authentication type is required by your API. Telzio supports Basic Authentication and Bearer Tokens.

Options

You can add one or more Options to your API Request action. Options are used for sending the call in multiple directions within the same call flow.

Options will show up in your call flow as Child Legs of your API Request, and you can direct calls to each option by specifying the Option Name in your API Response.

Webhook Request

Telzio sends a POST request to the URL specified in the Request URL field in your API Request action. The request contains a JSON payload with info about the call, the call flow and the API Request action settings.

The Content-Type header in your API response must be set to either text/xml or application/xml.

Important: Your API must respond with valid TelzioML within the Request Timeout defined in your API Request action settings. See the API Response for details about valid responses.

Example

{
  "call_id": "7-5e1484f1-e5",
  "from": "+18889989080",
  "from_cnam": "Telzio",
  "to": "+18887777996",
  "api_request": {
    "name": "My API Action",
    "options": [
      "option_1",
      "option_2"
    ]
  },
  "call_flow": {
    "flow_id": 34567,
    "name": "Main Call Flow"
  }
}

API Response

Your API must respond to the webhook with a TelzioML payload, including the instructions for how the call should continue in Telzio.

The API Request action supports the following Elements in the response:

  • <ApiRequest>
  • <Transfer>

Send Call to a Child Leg

The TelzioML example below lets the call continue within the same call flow and directs it to one of Options of your API Request. Use the <Option> element to specify the name of the option you want to direct the call to.

<?xml version="1.0" encoding="UTF-8"?>
<Response telzml="0.1">
  <ApiRequest>
    <Option>option_1</Option>
  </ApiRequest>
</Response>

Transfer Call to Another Call Flow

The example below transfers the call to a different Call Flow. You must specify the ID of the Call Flow you are transferring to, in the <Flow> element.

<?xml version="1.0" encoding="UTF-8"?>
<Response telzml="0.1">
  <Transfer>
    <Flow>1000</Flow>
  </Transfer>
</Response>

Transfer Call to a User

The example below will transfer the call to a user on your Telzio account. Use the <User> element to specify the username of the user you are transferring to.

<?xml version="1.0" encoding="UTF-8"?>
<Response telzml="0.1">
  <Transfer>
    <User>johnsmith</User>
  </Transfer>
</Response>

Transfer Call to a Group of Users

The example below will transfer the call to a group of users on your Telzio account. All users in the group will ring simultaneously and the first user to answer will get the call. Use the <Group> element to specify the ID of the user group you want to transfer the call to.

Logging and Debugging

The details and payload data of both the webhook request and your API's TelzioML response is logged for each call in your call log. This can be useful for seeing how your API responds to Telzio's webhooks when debugging your integration.

Telzio full API reference.