Actions

Actions allow your Sinch application to control individual calls. The following actions are currently available:

hangup

Hangs up a call.

Available to use in a response to an Incoming Call Event callback, an Answered Call Event callback, or a Prompt Input Event callback.

Example code

{
  • "action": {
    • "name": "hangup"
    }
}

Schema

name
required
string
Default: "hangup"

The name property. Must have the value hangup.

Value: "hangup"

continue

Continues to set up a call.

Available to use in a response to an Answered Call Event callback or a Prompt Input Event callback.

Example code

{
  • "action": {
    • "name": "continue"
    }
}

Schema

name
required
string
Default: "continue"

The name property. Must have the value continue.

Value: "continue"

connectPstn

Determines how a PSTN call is connected.

Available to use in a response to an Incoming Call Event callback or a Prompt Input Event callback.

Example code

{
  • "action": {
    • "name": "connectPstn",
    • "number": "+461234567890",
    • "locale": "en-US",
    • "maxDuration": 3000,
    • "dialTimeout": 10,
    • "cli": "+460987654321",
    • "suppressCallbacks": false,
    • "indications": "se",
    • "amd": {
      }
    }
}

Schema

name
required
string
Default: "connectPstn"

The name property. Must have the value connectPstn.

Value: "connectPstn"
number
string

Used to override where PSTN call is connected. If not specified, the extension the client called is used.

locale
string
Default: "en-US"

Specifies the locale. Uses the language code according to ISO 639, a dash (-), and a country code according to ISO 3166-1 alpha-2. If not specified, the default locale of en-US is used.

maxDuration
integer

The max duration of the call in seconds (max 14400 seconds). If the call is still connected at that time, it will be automatically disconnected.

dialTimeout
integer

The max duration the call will wait in ringing unanswered state before terminating with TIMEOUT/NO ANSWER on PSTN leg and NA/BUSYon MXP leg.

cli
string

Used to override the CLI (or caller ID) of the client. The phone number of the person who initiated the call is shown as the CLI. To set your own CLI, you may use your verified number or your Dashboard virtual number.

suppressCallbacks
boolean

If enabled, suppresses ACE and DICE callbacks for the call.

dtmf
string

A string that determines the DTMF tones to play to the callee when the call is picked up. Valid characters are: 0-9, #, and w. w renders a 500ms pause. For example, the string ww1234#w#, plays a 1 second pause, the DTMF tones for 1, 2, 3, 4, and #, followed by a 500ms pause and finally the # tone. This is useful if the callout destination requires a conference PIN code or an extension. If there is a calling party, it will hear progress while the DTMF is sent.

indications
string

The locale's tone to play while ringing.

Enum Value Description
at

Austria

au

Australia

bg

Bulgaria

br

Brazil

be

Belgium

ch

Switzerland

cl

Chile

cn

China

cz

Czech Republic

de

Germany

dk

Denmark

ee

Estonia

es

Spain

fi

Finland

fr

France

gr

Greece

hu

Hungary

il

Israel

in

India

it

Italy

lt

Lithuania

jp

Japan

mx

Mexico

my

Malaysia

nl

Netherlands

no

Norway

nz

New Zealand

ph

Philippines

pl

Poland

pt

Portugal

ru

Russia

se

Sweden

sg

Singapore

th

Thailand

uk

United Kingdom

us

United States

tw

Taiwan

ve

Venezuela

za

South Africa

object

An optional property used to enable Answering Machine Detection (AMD).

Note

You don't need to set cli or number if the values supplied by the client suffice.

connectMxp

Determines how an application-to-application call is connected.

Available to use in a response to an Incoming Call Event callback.

Example code

{
  • "action": {
    • "name": "connectMxp",
    • "destination": {
      • "type": "username",
      • "endpoint": "johndoe"
      },
    • "callHeaders": [
      • {
        • "key": "foo",
        • "value": "bar"
        },
      • {
        • "key": "baz",
        • "value": "qux"
        }
      ]
    }
}

Schema

name
required
string
Default: "connectMxp"

The name property. Must have the value connectMxp.

Value: "connectMxp"
object (destination)

The type of device and number or endpoint to call.

Array of objects (callHeader)

An optional parameter that allows you to specify or override call headers provided to the receiving Sinch SDK client. Read more about call headers here.

connectSip

Determines how to route a call to a SIP server.

Available to use in a response to an Incoming Call Event callback or a Prompt Input Event callback.

Example code

{
  • "action": {
    • "name": "connectSip",
    • "destination": {
      • "endpoint": "46708000000@sip.foo.com",
      • "type": "Sip"
      },
    • "maxDuration": 3000,
    • "cli": "private",
    • "transport": "tls",
    • "suppressCallbacks": false,
    • "callHeaders": [
      • {
        • "key": "foo",
        • "value": "bar"
        },
      • {
        • "key": "baz",
        • "value": "qux"
        }
      ]
    }
}

Schema

name
required
string
Default: "connectSip"

The name property. Must have the value connectSip.

Value: "connectSip"
required
object

Specifies where to route the SIP call.

maxDuration
integer

The max duration of the call in seconds (max 14400 seconds). If the call is still connected at that time, it will be automatically disconnected.

cli
string

Used to override the CLI (or caller ID) of the client. The phone number of the person who initiated the call is shown as the CLI. To set your own CLI, you may use your verified number or your Dashboard virtual number.

transport
string

An optional parameter to specify the SIP transport protocol. If unspecified, UDP is used.

Enum Value Description
UDP

User Datagram Protocol

TCP

Transmission Control Protocol

TLS

Transport Layer Security

suppressCallbacks
boolean

If enabled, suppresses ACE and DICE callbacks for the call.

Array of objects (callHeader)

Private SIP headers to send with the call.

moh
string

Means "music on hold". If this optional parameter is included, plays music to the connected participant if the SIP call is placed on hold. If moh isn't specified and the SIP call is placed on hold, the user will only hear silence while during the holding period .

Enum Value Description
ring

Plays a progress tone.

music1

Plays music choice 1.

music2

Plays music choice 2.

music3

Plays music choice 3.

Note

Make sure you allow our IP addresses in your SIP server for receiving this traffic. For more information on allowlisting see our SIP-trunking documentation.

connectStream

Important!
This feature is in closed beta - Please, contact Sinch sales for more details.

Determines how to route a call to a Stream/websocket server.

Available to use in a response to an Incoming Call Event callback.

Example code

{
  • "action": {
    • "name": "connectStream",
    • "destination": {
      • "type": "Websocket",
      • "endpoint": "wss://yourcompany.com/websocket-server"
      },
    • "maxDuration": 3000,
    • "callHeaders": [
      • {
        • "key": "foo",
        • "value": "bar"
        },
      • {
        • "key": "baz",
        • "value": "qux"
        }
      ]
    }
}

Schema

name
required
string
Default: "connectStream"

The name property. Must have the value connectStream.

Value: "connectStream"
required
object

Specifies where to route the Stream call.

maxDuration
integer

The max duration of the call in seconds (max 14400 seconds). If the call is still connected at that time, it will be automatically disconnected.

Array of objects (callHeader)

These custom parameters (headers/messages) are sent to your WebSocket server in the initial message when the ConnectStream is established.

Websocket data exchange - Init request

{
  • "codec": "pcm",
  • "sampleRate": 8000,
  • "callId": "1f21b71d-bdcd-430c-973f-c3b536e32ca0",
  • "timestamp": "2024-05-21T15:57:21.157027Z",
  • "applicationKey": "541c3e1c-09ac-4d4b-bdc8-76f90e0fc27f",
  • "version": 1,
  • "callHeaders": {
    • "foo": "bar",
    • "baz": "qux"
    }
}

Websocket data exchange - expected response

{
  • "status": "ok"
}
Note

After the server response is received Sinch will start to send binary messages and expects to receive binary messages back, enconded with the same CODEC received.

connectConf

Connects an incoming call to a conference.

Available to use in a response to an Incoming Call Event callback or a Prompt Input Event callback.

Example code

{
  • "action": {
    • "name": "connectConf",
    • "conferenceId": "myConference",
    • "moh": "ring"
    }
}

Schema

name
required
string
Default: "connectConf"

The name property. Must have the value connectConf.

Value: "connectConf"
conferenceId
required
string

The unique identifier of the conference. Shouldn't exceed 64 characters.

object

Options to control how DTMF signals are used by the participant in the conference. For information on how to use this feature, read more here.

moh
string

Means "music on hold". If this optional parameter is included, plays music to the first participant in a conference while they're alone and waiting for other participants to join. If moh isn't specified, the user will only hear silence while alone in the conference.

Enum Value Description
ring

Plays a progress tone.

music1

Plays music choice 1.

music2

Plays music choice 2.

music3

Plays music choice 3.

runMenu

Plays an interactive voice response (IVR) menu to the callee. This menu can play pre-recorded files or text-to-speech messages, collect DTMF tones, and trigger the Prompt Input Event (PIE) callback towards your backend, notifying you of the actions the callee took.

Available to use in a response to an Incoming Call Event callback or an Answered Call Event callback. Can also be used in combination with the Conferences endpoint of the Calling API.

Example code

{
  • "action": {
    • "name": "runMenu",
    • "barge": true,
    • "menus": [
      • {
        • "id": "main",
        • "mainPrompt": "#tts[Welcome to the main menu. Press 1 for support or 2 to continue.]",
        • "options": [
          • {
            • "dtmf": 1,
            • "action": "return(support)"
            },
          • {
            • "dtmf": 2,
            • "action": "menu(sub)"
            }
          ]
        },
      • {
        • "id": "sub",
        • "mainPrompt": "#tts[Welcome to the sub menu. Enter your 4-digit PIN.]",
        • "options": [
          • {
            • "dtmf": 1,
            • "action": "menu(main)"
            }
          ]
        }
      ]
    }
}

Schema

name
required
string
Default: "runMenu"

The name property. Must have the value runMenu.

Value: "runMenu"
barge
boolean
Default: true

'Barging' means that the user can press a DTMF digit before the prompt has finished playing. If a valid input is pressed, the message will stop playing and accept the input. If barge is disabled, the user must listen to the entire prompt before input is accepted. By default, barging is enabled.

locale
string

The voice and language you want to use for the text-to-speech message. This can either be defined by the ISO 639 locale and language code or by specifying a particular voice. Supported languages and voices are detailed here. If using the enableVoice to enable voice detection, the locale property is required in order to select the input language.

mainMenu
string

Selects the menu item from the menus array to play first.

enableVoice
boolean

Enables voice detection. If enabled, users can say their answers to prompts in addition to entering them using the keypad.

Array of objects (menu)

The list of menus available. The menu with the id value of main will always play first. If no menu has an id value of main, an error is returned.

park

"Parks" the call and places the caller on hold. The caller is placed into a loop, listening to an IVR prompt (either a pre-recorded audio file or generated by text to speech). If the call is unparked, prompts will stop playing immediately. If the max duration is reached, the last prompt will be fully played until the call ends.

Available to use in a response to an Incoming Call Event callback or a Prompt Input Event callback.

Example code

{
  • "action": {
    • "name": "park",
    • "introPrompt": "#tts[Welcome]",
    • "holdPrompt": "#tts[Thank you for your patience, your call is very important to us.]",
    • "maxDuration": 180
    }
}

Schema

name
required
string
Default: "park"

The name property. Must have the value park.

Value: "park"
locale
string

The voice and language you want to use for the text-to-speech message. This can either be defined by the ISO 639 locale and language code or by specifying a particular voice. Supported languages and voices are detailed here.

introPrompt
string

That prompt that is played when the call is first answered. You can use text-to-speech using the #tts[] element, SSML commands using the #ssml[] element.

holdPrompt
string

The prompt that is played on repeat until the call is unparked or the until the maxDuration value is reached. You can use text-to-speech using the #tts[] element, SSML commands using the #ssml[] element.

maxDuration
integer

The maximum amount of time in seconds that the holdPrompt will be played.

Limitation
The maxDuration value can be set to a maximum of 600 seconds (10 minutes).
We'd love to hear from you!
Rate this content:
Still have a question?
 
Ask the community.
SecurityPrivacyLegal & ComplianceCookie Statement
© 2024 Sinch. All rights reserved.