Cloud Voice

Voice Webhooks

On this page
  1. Specification
  2. Overview
  3. Security
  4. Response
  5. Events
  6. Call State Update
  7. Fax Ready
  8. Recording Ready
  9. Transcription Ready

Enfonica sends webhooks via HTTP(S) POST when certain events occur.

Looking to control a call?

This page documents asynchronous event notifications — CALL_STATE_UPDATE, FAX_READY, RECORDING_READY, and TRANSCRIPTION_READY. Your server returns a 2xx status and the response body is ignored. These webhooks do not control the call.

To control a call, your server responds to a VoiceML request with a VoiceML XML document. VoiceML requests are sent to a call's handler URIs and are a separate, synchronous request/response protocol.

Specification

Overview

The body of the request is a JSON serialized object.

The request will have header Content-Type: application/json; charset=utf-8.

The request will have header X-Enfonica-Event which specifies which event occurred.

Security

Enfonica signs every webhook with an HMAC-SHA256 signature included in the X-Enfonica-Signature header. See Request signing for details.

Response

Your server has 10 seconds to respond. A 2xx response means that your server handled the request. Enfonica follows a redirect, up to 5 times. Any other response, or no response in time, is a failure.

After a failure, Enfonica tries the next handler URL, if more than one is set. When every handler URL has failed, Enfonica tries 8 more times, after delays of 1, 2, 4, 8, 60, 1800, 3600, and 7200 seconds, and then stops. That's more than three hours in total.

Because a slow response is retried, your server can receive the same webhook more than once.

Events

Call State Update

When a call transitions to a new state, a call state update webhook will be sent to the configured URI.

The request will have X-Enfonica-Event: CALL_STATE_UPDATE.

The payload of the request will be a JSON serialized instance of the call of type enfonica.voice.v1beta1.Call.

Fax Ready

When a fax has been successfully received, a fax ready webhook will be sent to the configure URI.

The request will have X-Enfonica-Event: FAX_READY.

The payload of the request will be a JSON serialized instance of the fax of type [enfonica.voice.v1beta1.Fax].

The fax URI specified in the request is ephemeral and will expire in 24 hours. To retrieve the fax after this point, use the enfonica.voice.v1beta1.Faxes.GetFax RPC.

Recording Ready

When a recording has finished processing and is ready to access, this webhook will be sent to the URI specified:

  • if using <Record> action, against the RecordingReadyUri attribute.

The request will have X-Enfonica-Event: RECORDING_READY.

The payload of the request will be a JSON serialized instance of the recording of type enfonica.voice.v1beta1.Recording.

The audio URIs specified in the request are ephemeral and expire in 24 hours. To retrieve the audio after this point, use the enfonica.voice.v1beta1.Recordings.GetRecording RPC.

Transcription Ready

When a transcription has finished processing and is ready to access, this webhook will be sent to the URI specified:

  • if using <Record> action, against the TranscriptionReadyUri attribute.

The request will have X-Enfonica-Event: TRANSCRIPTION_READY.

The payload of the request will be a JSON serialized instance of the transcription of type enfonica.voice.v1beta1.Transcription.

Example payload

{
  "name": "projects/my-project/calls/sdfsd54g65sd4gsd89fsd56fsdf5sd/transcriptions/odnmd6sduje3dssd5s83d5sd8s35sd",
  "recording": "projects/my-project/calls/sdfsd54g65sd4gsd89fsd56fsdf5sd/recordings/ps56f38cs5dsjf45s82jmdso0r72sd",
  "state": "COMPLETED",
  "duration": "10.860s",
  "channelCount": 1,
  "createTime": "2021-06-23T03:12:55.183990Z",
  "updateTime": "2021-06-23T03:13:11.596854Z",
  "utterances": [
    {
      "channel": 0,
      "offset": "0.880s",
      "duration": "9.680s",
      "text": "Hi, this is Bob. I guess we're playing phone tag. Can you call me back. Thanks."
    }
  ]
}