Webhooks

Set up webhooks to receive real-time notifications and data responses after making API calls.

ℹ️ Note: Add a webhook URL to your request in order to receive information after the call.

---

Setting Up a Webhook

1. Specify the Webhook URL:

   • In your API request body, include the external_webhook_url key with the URL of your webhook receiver.

2. Test with the webhook:

   • For development and testing purposes, you can use Webhook.site to simulate receiving webhook data.

---

API Request Example

Include the following key-value pair in your API request body:

"external_webhook_url": "www.example.com/webhook_url"

---

Webhook Response Example

Upon completion of the call, the webhook URL will receive a response like the following:

{
    "status": "completed",
    "error_message": "agent_goodbye",
    "lead": {
        "name": "David",
        "phone_number": "[phone]"
    },
    "call": {
        "status": "completed",
        "end_call_reason": "completed",          
        "model_id": "1711241656808x745681686585854500",
        "timezone": "Europe/Berlin",
        "call_id": "1711646262471x768387119913843100",
        "duration": 32,
        "start_time": "2024-03-28T18:17:46.205134+01:00",
        "transcript": "\nbot:  Hello, I am calling from [company]! I've seen you complete our form on the website about selling. Do you have a couple of minutes to finish the request? \nhuman:  Yes. I want to buy a car.\nbot:  Oh, that's exciting! But let's focus on your property for now. Are you planning to sell it or rent it out? \nhuman:  I want to buy a car by"
    },
    "executed_actions": {
        "extract_info_1": {
            "name": "extract_info_1",
            "action_type": "extract_info_action_type",
            "description": "",
            "parameters_hard_coded": {
                "identifier": "purchase",
                "condition": "if user wants to purchase an item",
                "choices": null,
                "examples": [
                    "car",
                    "house"
                ]
            },
            "error_message": null,
            "return_value": {
                "purchase": "car"
            }
        }
    }
}

---

Understanding the Call Object States

The call object in the webhook response contains a status field, which can have various values indicating different states of the phone call:

Status Code	Description
completed	Phone call was successful.
failed	Phone call failed.
queue	Phone call is queued and will be executed.
paused	Phone call is put on hold.
initiated	Phone call has started.
no-answer	Phone call was not answered.
busy	Recipient's line was occupied with another call.
hangup_on_voicemail	Voicemail was detected and the call was terminated.

---

End Call Reason

The end_call_reason parameter provides insight into why a call ended:

Reason Code	Description
voicemail	The call was answered by voicemail.
human_goodbye	The call was answered by a human, and the human was the first to say goodbye.
agent_goodbye	The call was answered by a human, and the AI assistant was the first to say goodbye.
human_pick_up_cut_off	The call was answered by a human but was cut off abruptly without a proper goodbye.
max_duration	The call exceeded the maximum set duration.
undefined	The reason for the call ending is not specified.