​
POST_CALL_DATA Webhook Documentation

​
Overview

The POST_CALL_DATA webhook is an integral feature for building call processing workflows around Air’s conversational AI phone calls. When a call is completed and the prospect spoke to the agent, a POST request with detailed information about the call is sent to the configured URL. If the call goes to voicemail or cannot be completed, no event will be sent to the webhook.

​
Webhook Details

​
Trigger Event

The webhook is triggered after an AI phone call placed through Air is answered by a person. When the call concludes, Air will send a POST request to the webhook URL you have set up.

​
Example of POST Request Body

Below is an example of the data payload you will receive in the POST request: 
{
  "call": {
    "sid": "CAec7g2x30425ba039a83ffb4286754983",
    "llmAnsweredBy": "human",
    "promptId": 25673,
    "callRecordingUrl": "https://api.twilio.com/2010-04-01/Accounts/ACx495c401119e3f79c6f86yz760a6e287/Recordings/RE25a9z63a09998b44a8a444de055g6247",
    "fromNumber": "+17752432501",
    "toNumber": "+17752893647",
    "direction": "outbound-api",
    "duration": 44,
    "campaignId": null,
    "cachedLeadName": "Tyler",
    "transcript": "BOT: ~ \"Hey, Tyler!\"\nHUMAN:  how's it going\nBOT: Hey, Tyler!\nBOT: I'm Travis from the Biggest Little Flight School.\nBOT: I saw you expressed interest on our website that you want to learn more about flying.\nBOT: Do you remember that?\nHUMAN:  yeah i do\nBOT: ~ \"Awesome!\nBOT: I'm glad you remember.\nBOT: I can answer all your questions and provide you with more information.\nBOT: Also, would you like to book a time to come in and meet with some of our instructors?\"\nHUMAN:  yeah that'd be awesome\nBOT: ~ \"Great!\nBOT: So it looks like here we've got Monday, January 1st at 9:30 AM PST and Tuesday, January 2nd at 1:00 PM PST available.\nBOT: Which one works best for you?\"",
    "createdAt": "2023-12-31 23:12:05.62705+00",
    "leadData": null
  },
  "headers": {
    // Various headers including security tokens and client information...
  }
}
Please note: The above is an example payload and headers will vary based on each call.

​
Explanation of properties in the body of the request

The call object in the webhook payload contains several properties that provide detailed information about the AI phone call. Here’s a breakdown of each property:
  • sid: A unique identifier for the call session, used internally for tracking and referencing the call.
  • llmAnsweredBy: Specifies how the call was answered. The value “human” indicates that a person responded to the call. “human” is the only value that will come over with this property.
  • promptId: The identifier for the AI script or prompt used during the call, which corresponds to the id of your agent.
  • callRecordingUrl: The URL to access the recording of the call. This is useful for playback and analysis purposes.
  • fromNumber: The phone number from which Air initiated the call.
  • toNumber: The recipient’s phone number, i.e., the prospect who was called.
  • direction: Describes the direction of the call. “outbound-api” indicates an outgoing call.
  • duration: Length of the call in seconds.
  • campaignId: An identifier for the campaign that initiated this call, if applicable. A value of null means the call was instead initiated through the API or a roleplay.
  • cachedLeadName: The name of the lead/prospect that the call was initiated with.
  • transcript: The verbatim transcript of the dialogue between the Agent (BOT) and the human participant.
  • createdAt: The timestamp marking when the call record was created in the system, which is the time the call was initiated.
  • leadData: Any additional data about the lead. It’s null in this example, indicating there is no extra data or it’s not relevant for this particular call. Any metadata you initiate the call with will appear in this property.
These details are vital for post-call analysis and follow-up actions, providing a comprehensive view of the call’s context, engagement, and outcomes.

​
How to Set Up the Webhook

​
Video Demonstration

https://www.loom.com/share/3bddf705226f4695a2df5118594f67af

​
Steps to Configure

  1. Visit the Air Integrations Webhooks Page. settings-integrations.jpeg
  2. Click the “Create a Webhook” button located at the top right of the page. create-a-webhook.jpeg
  3. In the “Webhook Action” dropdown menu, choose “POST_CALL_DATA”. webhook-action.jpeg
  4. Enter the URL for the webhook receiver in the “Webhook URL” input field.
  5. In the “Bearer Token” field, input a secure token of your choice (16 characters or longer). If you do not require a bearer token, you may use a placeholder such as ‘fakeTokenGoesHere’. webhook-settings.jpeg
  6. With your webhook created, click “Test Webhooks” on the top right of the page, and verify you see a green checkmark, indicating success. If you see a red x instead, that means the webhook url you provided rejected our request and you need to check your configuration settings on the webhook. test-webhooks.jpeg
  7. Verify that you received the sample payload from the webhook test, and use this data structure to build your integration around. verify-payload.jpeg

​
Bearer Token Information

The Bearer Token is a security measure that allows you to recognize the signature of requests being sent to your webhook setup. It’s recommended to use a real token for production setups, however this is optional. Not verifying the Bearer Token in your system just means that anyone can make a request to your webhook URL. That’s up to your discretion.

​
Testing Your Webhook

To ensure your setup is correct, conduct a test by placing a call through Air and checking that the POST request is received with the correct data structure.

​
Need Help?

For support or questions regarding the POST_CALL_DATA webhook, contact our support team at support@air.ai.