Send Callflow

POST https://voice.8x8.com/api/v1/subaccounts/:subAccountId/callflows

Note: For all API requests that include a source parameter, CLID whitelisting is mandatory. Please contact your account manager or email cpaas-support@8x8.com if you have a voice account with 8x8 CPaaS.

Use Cases

The Callflows API enables you to build sophisticated voice solutions:

Interactive Voice Response (IVR)

Create interactive menu systems with DTMF capture, conditional routing, and voice prompts.

Voice Messaging

Deliver automated voice messages using text-to-speech (TTS) or pre-recorded audio files.

Custom Call Scenarios

Build tailored call flows by combining multiple actions (makeCall, say, playFile, sayAndCapture, hangup) to meet your specific business requirements.

API Examples

Example 1: IVR with DTMF Capture

{
"callflow":[
{
"action":"makeCall",
"params":{
"source":"+6588000000",
"destination":"+6590000000"
}
},
{
"action":"sayAndCapture",
"params":{
"promptMessage":"Press 1 for Sales, Press 2 for Support",
"voiceProfile":"en-US-Neural2-C",
"minDigits":1,
"maxDigits":1,
"digitTimeout":5000,
"completeOnHash":false
}
}
]
}

Example 2: Voice Message (Text-to-Speech)

{
"callflow":[
{
"action":"makeCall",
"params":{
"source":"+6588000000",
"destination":"+6590000000"
}
},
{
"action":"say",
"params":{
"text":"Hello, this is a reminder about your appointment tomorrow at 2 PM.",
"voiceProfile":"en-GB-Emma",
"repetition":1,
"speed":1
}
},
{
"action":"hangup"
}
]
}

Example 3: Voice Message (Audio File)

{
"callflow":[
{
"action":"makeCall",
"params":{
"source":"+6588000000",
"destination":"+6590000000"
}
},
{
"action":"playFile",
"params":{
"fileUrl":"https://example.com/audio/notification.mp3",
"repetition":1
}
},
{
"action":"hangup"
}
]
}

Request

Path Parameters

    subAccountId stringrequired

    Possible values: >= 3 characters and <= 50 characters, Value must match regular expression ^[A-Za-z0-9\-._&]{3,50}$

    You must replace {subAccountId} with the subaccountid that you want to use. By default this is generated once you have completed the voice onboarding.

Body

  • To send a Voice callflow Message using the 8x8 Voice Message API you need to POST a JSON object to the url defined above.
  • Additionally it is required to set either a language code or a voice profile in the request, to guarantee the correct pronunciation of the voice message.
  • The JSON object takes the following properties:
    anyOf
    validUntilstring

    Optional date time. format: YYYY-MM-DDTHH:MM:SS.SSSZ

    callflow object[]

  • Array [
    • anyOf
    actionstring

    makeCall enables you to create an outbound voice call to a specified destination with the caller id specified as source. Once the call is answered by the receiving party, the rest of the callflow actions will be executed in sequence. If two makeCall actions are used in the same callflow, the 2nd call will be bridged to the 1st call once answered. Currently, we do not support call conferencing, so the maximum allowed makeCall actions in a callflow is 2.

    Possible values: [makeCall]

    params object

    sourcestringrequired

    Originator phone number. For CLIDs that have been whitelisted and CLID overwrite is enabled for the subaccount, please set the CLID as "6588000000".

    Example: [+][country code][88000000]
    destinationstringrequired

    Destination phone number in E.164 international format.

    Example: +6590000000[+][country code][subscriber number including area code]
    actionstring

    Say enables you to convert the given text into a speech and play it in the currently active call.

    Possible values: [say]

    params object

    textstringrequired

    The message body content to be converted to voice. Maximum voice message length is 3000 characters

    Example: Hi, This is a test message from 8x8
    voiceProfilestringrequired

    Choose one of the available Voice profiles to define the voice, gender and accent for the message you are sending. To see all available speech profiles, please send an API request to https://developer.8x8.com/connect/reference/get-voice-profile-information endpoint to retrieve voice profiles that 8x8 supports

    Example: en-GB-Emma
    repetitioninteger

    The amount of times to repeat the voice message during the call. Accepted values are 1, 2 or 3. Default value is 1 for no repeat.

    Example: 1
    speedinteger

    Reproduction speed of speech in the resulting message. Accepted values range from 0.5 - 2, as a two digit number. The default value is 1.

    Example: 1
    actionstring

    sayAndCapture - Plays a voice file in to the call and then captures users DTMF input and reports back the DTMF via Voice Call Action (VCA) webhook. https://developer.8x8.com/connect/reference/voice-call-action-webhook

    Possible values: [sayAndCapture]

    params object

    promptMessagestring

    The message body content to be converted to voice. Maximum voice message length is 3000 characters

    voiceProfilestring

    Choose one of the available Voice profiles to define the voice, gender and accent for the message you are sending. To see all available speech profiles, please send an API request to https://developer.8x8.com/connect/reference/get-voice-profile-information endpoint to retrieve voice profiles that 8x8 supports

    Example: en-GB-Emma
    speedinteger

    Reproduction speed of speech in the resulting message. Accepted values range from 0.5 - 2, as a two digit number. The default value is 1.

    minDigitsintegernullable

    min no of digits to be pressed by user before call back is triggered

    Possible values: >= 1

    Default value: 1
    maxDigitsintegernullable

    max no of digits to be pressed by user before call back is triggered

    Possible values: >= 1

    Default value: 1
    digitTimeoutintegernullable

    max time for dtmf tones being captured

    Possible values: >= 1

    overallTimeoutintegernullable

    max call duration

    Possible values: >= 1

    Default value: 5000
    completeOnHashbooleannullable

    if the dtmf callback should be triggered on hash

    Default value: true
    noOfTriesintegernullable

    max no of times to play message if user doesn't provide input

    Possible values: >= 1

    Default value: 1
    successMessagestringnullable
    failureMessagestringnullable
    actionstring

    playFile enables you to send an audio recording to an end user.

    Possible values: [playFile]

    params object

    fileUrlstringrequired

    url of the audio to be played in the call

    • supported protocols - http, https
    • max file size - 5120 KB
    • supported media formats - mp3, wav
    repetitioninteger

    No of times to repeat the audio file content. Accepted values are 1, 2 or 3. Default is 1 (no repeat).

    actionstring

    Hangup - Disconnects all active calls. This will terminate the session, triggering the session summary webhook.

    Possible values: [hangup]

  • ]

Should the request authenticate successfully and pass all validation, the response will contain an updated Voice Message Object. The following is an example response:

Schema

    sessionIdstringrequired

    The unique id of the callflow session.

    sessionStatusstringrequired

    The status of the callflow session.

    callFlowRequestIdstringrequired

    The unique id of the callflow request.

    validUntilstring<date-time>

    The time until which the callflow session is valid.

    statusCodeintegerrequired

    The status code of the callflow session.

    statusMessagestringrequired

    The status message of the callflow session.

{
"sessionId":"03cc8cac-376b-11ef-a28b-0582ff0039d5",
"sessionStatus":"CREATED",
"callFlowRequestId":"03cc3e8b-376b-11ef-a28b-4dd5d900ecb3",
"validUntil":"2024-07-01T05:50:23.550Z",
"statusCode":1,
"statusMessage":"Created"
}
{
"sessionId":"03cc8cac-376b-11ef-a28b-0582ff0039d5",
"sessionStatus":"CREATED",
"callFlowRequestId":"03cc3e8b-376b-11ef-a28b-4dd5d900ecb3",
"statusCode":1,
"statusMessage":"Created"
}

Schema

    sessionStatusstringrequired

    The status of the callflow session.

    callFlowRequestIdstringrequired

    The unique id of the callflow request.

    statusCodeintegerrequired

    The status code of the callflow session.

    statusMessagestringrequired

    The status message of the callflow session.

{
"sessionStatus":"string",
"callFlowRequestId":"string",
"statusCode":0,
"statusMessage":"string"
}
{
"sessionStatus":"NOT_CREATED",
"callFlowRequestId":"c6e6dee5-3846-11ef-9e95-b903e2ed7273",
"statusCode":-1007,
"statusMessage":"$.callflow[0].action should be one of: say,playFile,sayAndCapture"
}

Schema

    sessionStatusstringrequired

    The status of the callflow session.

    callFlowRequestIdstringrequired

    The unique id of the callflow request.

    statusCodeintegerrequired

    The status code of the callflow session.

    statusMessagestringrequired

    The status message of the callflow session.

{
"sessionStatus":"string",
"callFlowRequestId":"string",
"statusCode":0,
"statusMessage":"string"
}
{
"sessionStatus":"NOT_CREATED",
"callFlowRequestId":"fd2fc658-3845-11ef-9e95-b903e2ed7273",
"statusCode":401,
"statusMessage":"Authentication header not found or token invalid"
}

Schema

    sessionStatusstringrequired

    The status of the callflow session.

    callFlowRequestIdstringrequired

    The unique id of the callflow request.

    statusCodeintegerrequired

    The status code of the callflow session.

    statusMessagestringrequired

    The status message of the callflow session.

{
"sessionStatus":"string",
"callFlowRequestId":"string",
"statusCode":0,
"statusMessage":"string"
}
{
"sessionStatus":"NOT_CREATED",
"callFlowRequestId":"9e209996-3845-11ef-9e95-b903e2ed7273",
"statusCode":404,
"statusMessage":"SubAccount not found by Id : 8x8_Testing"
}

Schema

    sessionStatusstringrequired

    The status of the callflow session.

    callFlowRequestIdstringrequired

    The unique id of the callflow request.

    statusCodeintegerrequired

    The status code of the callflow session.

    statusMessagestringrequired

    The status message of the callflow session.

{
"sessionStatus":"string",
"callFlowRequestId":"string",
"statusCode":0,
"statusMessage":"string"
}
{
"sessionStatus":"NOT_CREATED",
"callFlowRequestId":"767ca1b8-3846-11ef-9e95-b903e2ed7273",
"statusCode":-1013,
"statusMessage":"Invalid Callflow : First action should be a MakeCall action"
}

Schema

    sessionStatusstringrequired

    The status of the callflow session.

    callFlowRequestIdstringrequired

    The unique id of the callflow request.

    statusCodeintegerrequired

    The status code of the callflow session.

    statusMessagestringrequired

    The status message of the callflow session.

{
"sessionStatus":"string",
"callFlowRequestId":"string",
"statusCode":0,
"statusMessage":"string"
}
{
"sessionStatus":"NOT_CREATED",
"callFlowRequestId":"767ca1b8-3846-11ef-9e95-b903e2ed7273",
"statusCode":500,
"statusMessage":"Internal server error"
}

Source: https://developer.8x8.com/connect/reference/ivr · 8x8 CPaaS Developer Docs. Synced for support deflection.

Was this article helpful?
or
0 out of 0 found this helpful
Avatar
Stephen - 8x8 Technical Support Level 2

0 Comments

Please sign in to leave a comment.

Didn't find what you were looking for?

Submit a request