API Reference
HomeChangelogAcademy

Webhook

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

ℹ️

Add a webhook URL to the request in order to receive information after the call.

Setting Up a Webhook

  • Specify the Webhook URL: In your API request body, include the external_webhook_url key with the URL of your webhook receiver.
  • 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.exmaple.com/webhool_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": "+1234334546"
    },
    "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 Majestic Estates! 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, each indicating a different state of the phone call. Below is a table explaining these statuses:

Status CodeDescription
completedPhone call was successful.
failedPhone call failed.
queuePhone call is queued and will be executed.
pausedPhone call is put on hold.
initiatedPhone call has been started
no-answerPhone call has not been answered.
busyRecipient's line is occupied with another call.
hangup_on_voicemailVoicemail was detected and the call was terminated

End Call Reason

This end_call_reason parameter provides insight into the reason why a call ended:

Reason CodeDescription
voicemailThe call was answered by voicemail.
human_goodbyeThe call was answered by a human, and the human was the first to say goodbye.
agent_goodbyeThe call was answered by a human, and the agent was the first to say goodbye.
human_pick_up_cut_offThe call was answered by a human but was cut off abruptly without a proper goodbye.
max_durationThe call exceeded the maximum set duration.
undefinedThe reason for the call ending is not specified.