Developers

Getting Started

Explore ASK-FAST apis

For a more detailed API description, please go here

Introduction

This tutorial shows you how you can start building your first dialog with ASK-Fast.

This tutorial assumes that you have a (free) ASK-Fast account. If you don’t have an ASK-Fast account yet, click here to register.

Basic flow

When an outbound call is requested by the client the Ask-Fast Server performs an HTTP GET request on the URL provided in an attempt to fetch a question. Questions form the basis of a dialog scenario, with one question linked to the other questions by URLs (more information on the format of the question can be found here). This makes it possible for ASK-Fast to fetch the sequence of all questions to complete a particular scenario.

All of the following API calls can be mimicked using any REST API builder tool. E.g. POSTMAN

Set up an outbound communication request

Step 1 : Get Access token

To initiate a dialog, e.g. start a phone call, sms etc, an accessToken must be received from ASK-Fast. This can be done by using the following API:

POST http://api.ask-fast.com/keyserver/token
                        
x-www-form-urlencoded data:

client_id         :<accountID>
grant_type        :refresh_token
refresh_token     :<refreshToken>
client_secret     :none

Response format:
{"expires_in": 3600, "refresh_token": "<refreshToken>", "access_token": "<accessToken>"}

Where :

accountId and refreshToken can be obtained from your account dashboard.

Step 2 : Call Initiation API

This step contains a request followed by a response. Outbound calls refers to all outgoing communication, not just phone calls. To initiate an outbound call, perform the HTTP request below. This will ensure that your account and thequestion (accessed via the URL) is setup properly. The fields in bold are mandatory. question (accessed via the URL) is setup properly. The fields in bold are mandatory.

POST https://api.ask-fast.com/startDialog

Headers : Content-Type: application/json Authorization: Bearer <accessToken>

Payload : { "adapterType":"<CALL|SMS|EMAIL|XMPP|PAGER>", "address": "<address to be reached>", "url": "<CallControl URL>", "senderName": "<callerId for the communication>" }

Where :

  • accessToken: is a unique Id valid for 60 minutes generated as described in this step.
  • addapterType: Is the medium intended for this communication. ASK-Fast supports phone calls (CALL), texts (SMS), emails (EMAIL) and jabber/xmpp chat (XMPP).
  • address: Is the address to which an outbound call is to be performed. E.g. phone number in case of SMS or phone call, email address in case of email or xmpp, etcetera. If you need to reach multiple addresses, use one of the following formats instead of the address field:
    • addressList: A list of address in the format ["address1", "address2", ...] , you can add as many addresses as you want in this field.
    • addressMap: If you want to broadcast emails, you have the option to add a recipient name too. Use this format to add multiple recipients:
      "addressMap": {
              "address1": "Recipient1 Name",
              "address2": "Recipient2 Name"
      }
    • addressCcMap: Use this format to add Carbon Copies (CC) to your email(s):
      "addressCcMap": {
              "address1": "Recipient1 Name",
              "address2": "Recipient2 Name"
      }
    • addressBccMap: Use this format to add Blind Carbon Copies (BCC) to your email(s):
      "addressBccMap": {
              "address1": "Recipient1 Name",
              "address2": "Recipient2 Name"
      }
  • url: This is the URL to fetch the question. ASK-Fast performs an HTTP GET request on this URL and expects a response in a question format in return. The following query parameters are appended to the given URL:
    • sessionKey: This is a unique id specific for this type of communication request. This can be useful to fetch corresponding communication logs.
    • responder: Address of the recipient.
    • requester: This is the address of the communication channel (adapter) which is used to make the request.
  • senderName: This depends on the type of communication channel (adapterType) selected.
    • For CALL and PAGER, the senderName has to be a verified number. Alphanumerics are not allowed.
    • For SMS, please be aware that this option is not supported by all operators. It has a maximum length of 14 digits or 11 characters. Only the following characters are possible: A to Z, a to z and 0 to 9. No spaces or any other symbols and characters are possible. When sending to certain countries (e.g. Belgium) you are obliged to select a shortcode because it’s not possible to deliver an SMS using an alphanumeric sender id.
    • For EMAIL, any senderName is possible. If it is an email address, it will be added to the "reply-to".
RESPONSE:
{
        "version": "<current ASK-Fast platform version>",
        "result": {
              "<address1>": "sessionKey1",
              "<address2>": "sessionKey2"
        "},
        "code": <statusCode>,
        "message": <server message>,
}

Where :

address(N): Is the addresses of the recipient.
sessionKey(N): Is the unique key generated by ASK-Fast to track individual communication request. You can use this to filter logs in the portal.
code: The HTTP status code. 200 means a successful call. Any other code is not a successful call. The details of which is added to the message field.

Step 3 : Call Control APIs

Step 3a : Essence of ASKing questions

As explained in the Basic flow , a dialog scenario consists of questions. These questions contain URLs, and these URLs must be accessible to ASK-Fast.

The general format of a JSON question looks like this:

{
        "question_id": <some_id>,
        "question_text": <text or url>,
        "type": [open|closed|comment|referral|conference|exit|reject],
        "url": <referral url>,
        "answers": [
                {
                        "answer_id": <some_id>,
                        "answer_text": <text or url>,
                        "callback": <answer_callback_url>
                }
        ],
        "event_callbacks":[
          {
                        "event": [answered|timeout|hangup|exception|delivered],
                        "callback": <event_callback_url>
          }
        ],
        "media_properties":[
                {
                      "medium": [BROADSOFT|XMPP|SMS|EMAIL],
                      "properties": {
                          <MediumPropertyKey>: <PropertyValue>
                        }
                }
        ]
}

Where :

  • question_text: If it is a simple text, it should be prefixed with text://. This could also be an HTTP url which returns the text to be processed by ask-fast. If it's a phone call, it'll be spoken by our TTS engine.
  • type: This dictates the control sequence on the scenario.
    • OPEN question is generally used in cases when the answer does not have a small subset of answers. For example: "What is your name?"
    • CLOSED question is generally used when the sequence has a small subset of answers. For example: "Are you free today? [Yes | No]"
    • COMMENT is used to send or play a text without expecting an answer in return.
    • REFERRAL question is generally used to redirect the sequence to a different phone number. The URL field is expected to have a phone number prefixed like this example
    • CONFERENCE question is specific for phone call and creates a conference between numbers. A unique conference room name has to be chosen and passed in the media properties with property key. For example: "CONFERENCE_ROOM_NAME".
    • EXIT is used to end a conversation. ASK-Fast will also end a conversation automatically if an error occurs or if no more actions have to be performed.
    • REJECT is used to reject a call without picking up.
  • answer_text: This is the marker for making a corresponding match in the response received by the user. E.g. if the answer_text is “Yes, I am free”, and the response received matches it, an HTTP POST callback is done to the given corresponding answer_callback_urlThis is explained in this section
  • event_callbacks: Communication progress events are HTTP posted to the given corresponding event_callback_url. This section explains more about this process.
  • media_properties: Are optional media specific properties used to explicitly define/configure a communication session. The MediumPropertyKey can be one of the following:
    • TIMEOUT: (restricted to a phone call) Defines the timeout associated with the call. Default value of ten seconds is used for a no answer input on a closed question. Forty seconds are used for a call timeout for a redirection (referral question). Five seconds are used for a a no answer input on an open question.
    • ANSWER_INPUT: (This is an experimental feature!!) Not restricted to any channel) Defines if the answer is given via dtmf, text etc. Default value depends on the channel used. For a phone call “dtmf” is used as standard, while “text” is used for other text based channels such as SMS, EMAIL etc.
    • ANSWER_INPUT_MIN_LENGTH, ANSWER_INPUT_MAX_LENGTH: (Restricted to to phone calls) Defines the length of the answer input. Typically used with dtmf input.
    • TYPE Defines a subtype for the question type. For example open question with type “audio” refers to voicemail. By default a minimum value of “1” and unbounded maximum value is taken.
    • VOICE_MESSAGE_LENGTH: (Restricted to phone calls) Defines the length of the voicemail to be recorded. By default fifteen seconds is used as the length of the voice message.
    • RETRY_LIMIT (Currently restricted to phone calls) Defines the number of times the question should be repeated in case the input from user to the question is wrong. This works only for phone call to end a call with repeated input errors. Default value of "5" is used.
    • VOICE_MESSAGE_BEEP (Restricted to phone calls) Boolean flag to indicate if a voice message start should be indicated by a beep or nothing. Default value is "true".
    • DTMF_TERMINATE (Restricted to phone calls) Boolean flag to indicate if the call should terminate when a dtmf is pressed. Default value is "true".
    • TSS_SPEED (Restricted to phone calls) Defines the speed at which the TTS is spoken by the TTS engine. Default value: “0”. Range: [-10, 10] where -10 is the slowest and 10 is the fastest.
Step 3b : Trigger Answers

The answers are passed to the answer callback url with the following payload. Examples of answers can be DTMF input in phone calls, SMS texts, Emails.

{
        "question_id": <questionId>,
        "answer_id": <answerId>,
        "answer_text": <answer by responder>,
        "responder": <address of responder>,
        "extras": {
              "requester":<address of communication channel/adapter>,
                "adapterId":<uniqueId identifying the adapter used>,
                "sessionKey":<uniqueId identifying this communication>
        }
}
Step 3c : Trigger events

The following event callbacks can be used to capture any events while a scenario is in progress.

"event_callbacks": [
        {
                "event": [answered|timeout|exception|hangup|delivered],
                "callback": <url>
        }
]

Where :

  • answered: Is used to trigger a callback when a phone call or pager is answered by the receiver.
  • timeout When a phone call is missed by the receiver.
  • exception When a phone call is not triggered for miscellaneous reasons.
  • hangup When the caller end the call.
  • delivered When an SMS is delivered to the receiver. This is a special callback with paylaod as described here here

The POST request initiated on the callback url carries the following payload (unless it is of delivered type):

{
        "responder":<address of responder>,
        "question_id":<questionId>,
        "event":<event type>,
        "extras": {
                <optional/additional information about this event>
        },
        "message":<string describing the event, error message>
}

Where :

extras: has a key, value pair of any additional information related to this event.

For example :
"extras": {
        "startTime": 1382623574000,
        "releaseTime": 1382624584000,
        "answerTime": 1382623584000
}

carries the startTime (timestamp at which the phone call started), answerTime (timestamp at which the phone call was answered) and releaseTime (timestamp at which the phone call was hung up).

Delivered event callback payload:

{
        "reference": <uniqueReferenceKey>,
        "sms": <actual SMS text that is delivered>,
        "adapterID": <adapterId that is used for this SMS>,
        "callback": <deliveryCallback Used>,
        "host": <ASK-Fast Host>,
        "remoteAddress": <number to which SMS is delivered>,
        "localAddress": <the senderName used>,
        "sentTimeStamp": <sms sent timestamp in format: 2016-06-10T15:37:12>,
        "deliveredTimeStamp": <sms delivered timestamp in format: 2016-06-10T15:37:12>,
        "statusCode": <one of: UNKNOWN|EXPIRED|DELETED|UNDELIVERED|REJECTED|ACKNOWLEDGED|ENROUTE|DELIVERED|ACCEPTED>,
        "description": <additional details>,
        "accountId": <ASK-Fast account id>,
        "ddrRecordId": <the corresponding LogId>,
}

Example

Availability over phone

Following is a simple example to trigger a phone call using ASK-Fast API to collect availability of a person.

  1. Initiate a phone call as described This will initiate a phone call to phoneNumber1 and perform the call control sequence as implemented in the URL
    POST https://api.ask-fast.com/startDialog
    Headers:
    Content-Type: application/json
    Authorization: Bearer <BearerToken>
    {
            "adapterType":"CALL",
            "address":"phoneNumber1",
            "url":"http://api.ask-fast.com/question/appointment"
    }
  2. In this call control implementation, the recipient at phoneNumber1 has the option of pressing 1 for "Yes" or 2 for "No".
  3. On pressing 1, ASK-Fast does an HTTP POST request at: http://api.ask-fast.com/question/appointment/yes with payload similar to:
    {
            "question_id":"1",
            "answer_id":"a3704236-bc18-43ea-b940-e4d41abf65a5",
            "answer_text":"1",
            "responder":"phoneNumber1",
            "extras": {
                    "requester": <ASK-Fast phoneNumber>,
                    "adapterId": <ASK-Fast adapterId used>,
                    "sessionKey": "3542f2c3-ccd4-4bee-bfc5-98bb3c926a3a"
            }
    }
  4. A follow-up question to collect the number of hours available for is received:
    {
            "preferred_language": "nl",
            "question_id": "11",
            "question_text": "text://How long are you available? (in mins)",
            "type": "open",
            "answers": [
                    {
                          "answer_id": "a6e4e7cf-ea49-4558-9820-6a7b18eeffcc",
                            "answer_text": "text://",
                            "callback": "http://api.ask-fast.com/question?url=Thanks+for+accepting+the+invitation%21&appendAnswer=true",
                    }
            ],
            "event_callbacks": [],
            "media_properties": [],
    }
  5. An input of 2 (implying 2 hours for example) will be POSTed to:
    http://api.ask-fast.com/question?url=Thanks+for+accepting+the+invitation%21&appendAnswer=true
    with payload:
    {
            "question_id":"11",
            "answer_id":"a6e4e7cf-ea49-4558-9820-6a7b18eeffcc",
            "answer_text":"2",
            "responder":"phoneNumber1",
            "extras": {
                      "requester": <ASK-Fast phoneNumber>,
                        "adapterId": <ASK-Fast adapterId used>,
                        "sessionKey": "3542f2c3-ccd4-4bee-bfc5-98bb3c926a3a"
            }
    }

    and expect a reply similar to:

    {
            "preferred_language": "nl",
            "question_id": "111",
            "question_text": "text://You pressed 2. Thanks for accepting the invitation!",
            "type": "comment",
            "answers": [],
            "event_callbacks": []
    }
Availability over sms

We want to repeat the same scenario of collecting availability of a person via SMS instead of a phone call.

Initiate an sms call as described This will initiate an SMS call to phoneNumber1 and perform the call control sequence as implemented in the url. By default, SMS callerId is configured to be a text (E.g. ASKFast), so in order to enable the recipient to respond we have to include a senderName parameter in the request. Currently only Dutch callerId is supported.

POST https://api.ask-fast.com/startDialog
Headers:
Content-Type: application/json
Authorization: Bearer <BearerToken>
{
        "adapterType":"SMS",
        "address":"phoneNumber1",
        "senderName":"0635253626",
        "url":"http://api.ask-fast.com/question/appointment"
}

The rest of the call control sequences are similar to the phone call scenario. Instead of Pressing 1 for “Yes” and 2 for “No” in the phone scenario, the user will have to respond via SMS with “Yes” or “No” itself.