Dial API

/call/dial allows initiating an outgoing call from the Cognitive Voice Gateway to start conversations. Once the call is established, the bot configured by the project will take over the conversation, exactly like it would in case of dial-in.

Tip

Contact us to enable outgoing calls for your CVG project. Initiating outgoing calls is disabled by default.

Answering Machine Detection

One common problem with automated calls are answering machines: People might not be at their phones or in a situation where they are unable or unwilling to accept the incoming call. In those cases, an answering machine or something similar will pick up the call. To handle those cases more gracefully, we provide the option to automatically detect and reject answering machines (option acceptAnsweringMachines).

However, do not expect a 100% detection rate of answering machines as this feature relies on voice analysis with many heuristics. For that reason, even if the call is configured to reject answering machines, the voice bot should be able to handle those answering machines gracefully in case of a failed detection. Before the call connects and the voice bot takes over, the answering machine detection introduces a short delay. During this delay, the algorithm listens to the voice of the callee to analyze it. This process can take up to 5 seconds.

Caller ID Override

To change the caller ID seen by the callee, the API provides the option callerId. Similar to the answering machine detection, this functionality must be considered a “best-effort” without any guarantees that the given value will be shown to the callee as intended. Any gateway the SIP traffic passes on the way to the destination phone can filter these options and replace them with new values. In the case of a caller ID modification, the Cognitive Voice Gateway has no feedback channel to detect those modifications. While this option should generally work, your voice bot process should not rely on the correct number being displayed to the end-user.

Call Status Feedback

The HTTP request of the called API will be kept alive until the call has either been established successfully or failed for any reason. Note that closing the connection of the API call (through short read timeouts or intentional) will not cancel the dial-out process.

If the call has been established successfully and the bot has taken over, the HTTP response will contain a dialog ID. Use this ID to access the dialog history.

If the call could not be establishd, the response will provide a detailed reason if possible.