openapi: 3.0.3
info:
title: Callbook AI - Call Trigger API
description: |
This API allows triggering calls to customers through Callbook AI's assistant system.
Calls are initiated using an assistant ID and must include the phone number as a required field.
After the call, Callbook AI can send results to a provided webhook URL.
version: 1.0.0
contact:
name: Callbook AI Support
email: support@callbook.ai
url: https://callbook.ai
servers:
- url: https://api.callbook.ai
description: Production Server
tags:
- name: Calls
description: Endpoints for triggering and managing AI-driven calls.
- name: Webhooks
description: Endpoints for receiving call results or other notifications.
paths:
/crm/webhook/new_call/api/{ASSISTANT_ID}:
post:
tags:
- Calls
summary: Trigger a new call
description: |
Initiates a new call using a specific assistant ID.
The request body must contain at least a phone number.
Optionally, a `callback_url` can be provided where Callbook AI will send call results after completion.
security:
- BearerAuth: []
parameters:
- name: ASSISTANT_ID
in: path
required: true
description: The unique identifier of the assistant initiating the call.
schema:
type: string
example: "assistant_123456"
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
phone:
type: string
description: The customer's phone number (required).
example: "+14155552671"
name:
type: string
description: The customer's name (optional but recommended).
example: "John Doe"
callback_url:
type: string
format: uri
description: (Optional) A webhook URL where Callbook AI will send the call results after completion.
example: "https://yourserver.com/webhook/call_results"
next_payment:
type: string
description: (Optional) The customer's next payment date.
example: "2025-02-10"
last_purchase_date:
type: string
description: (Optional) The last date of purchase.
example: "2025-01-15"
product_interest:
type: string
description: (Optional) The product or service the customer is interested in.
example: "Premium Plan"
location:
type: string
description: (Optional) The customer's location.
example: "New York"
responses:
"200":
description: Call successfully triggered.
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: "success"
call_id:
type: string
example: "call_789456"
"400":
description: Bad request (missing required fields).
"401":
description: Unauthorized (invalid or missing JWT token).
"500":
description: Internal server error.
/webhook/call_results:
post:
tags:
- Webhooks
summary: Receive call results
description: |
This endpoint should be implemented by clients to receive call results from Callbook AI.
If a `callback_url` was provided when triggering the call, Callbook AI will send a `POST` request to it with the following structure.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
call_id:
type: string
description: The unique identifier of the call.
example: "call_789456"
assistant_id:
type: string
description: The assistant that handled the call.
example: "assistant_123456"
transcription:
type: array
description: The transcription of the conversation.
items:
type: object
properties:
speaker:
type: string
enum: [user, assistant]
description: The speaker of each message.
example: "user"
text:
type: string
description: The spoken text.
example: "Hello, I need help with my order."
variables:
type: object
description: Key-value pairs with additional call metadata.
properties:
voicemail:
type: boolean
description: Whether the call reached voicemail.
example: true
call_duration:
type: integer
description: Duration of the call in seconds.
example: 45
custom_field_1:
type: string
description: (Optional) Any custom field related to the assistant's configuration.
example: "Custom Value"
custom_field_2:
type: string
description: (Optional) Another custom field related to the assistant's configuration.
example: "Another Value"
responses:
"200":
description: Webhook received successfully.
content:
application/json:
schema:
type: object
properties:
phone_number:
type: string
country_code:
type: string
whole_number:
type: string
duration:
type: integer
status:
type: string
audio:
type: string
phone:
type: string
name:
type: string
voicemail:
type: string
user_asked_to_be_called_again:
type: string
examples:
mockExample:
summary: Example of a successful call result
value:
phone_number: "3151234567"
country_code: "57"
whole_number: "+573151234567"
duration: 5
status: "finished"
audio: "https://phoneai.s3.amazonaws.com/call_recordings/ca_55ba7a51-48a1-4564-8b5b-cab0b73c45a3.wav"
phone: "+573151234567"
name: "Carolina"
voicemail: "NO"
user_asked_to_be_called_again: ""
"400":
description: Bad request (invalid data).
"500":
description: Internal server error.
/calls/client/{client_id}:
get:
tags:
- Calls
summary: Retrieve call statistics by client ID
description: |
Retrieves calls from the database for a given `client_id` inside `crm_data`.
Returns the number of calls, total duration, and breakdown of statuses (e.g., finished, unanswered, failed).
security:
- BearerAuth: []
parameters:
- name: client_id
in: path
required: true
description: The unique client ID associated with the calls.
schema:
type: string
example: "ac8238ec-1689-40d0-8bd8-18af6141f5f5"
responses:
"200":
description: Successfully retrieved call statistics.
content:
application/json:
schema:
type: object
properties:
client_id:
type: string
description: The client ID queried.
example: "ac8238ec-1689-40d0-8bd8-18af6141f5f5"
total_calls:
type: integer
description: Total number of calls for this client.
example: 5
total_duration:
type: integer
description: Sum of all call durations (in seconds).
example: 350
status_counts:
type: object
properties:
finished:
type: integer
description: Number of completed calls.
example: 3
unanswered:
type: integer
description: Number of unanswered calls.
example: 1
failed:
type: integer
description: Number of failed calls.
example: 1
"400":
description: Bad request (missing client_id).
"401":
description: Unauthorized (invalid or missing Bearer token).
"404":
description: No calls found for the provided client ID.
"500":
description: Internal server error.
/generate_voice_note:
post:
tags:
- Voice Notes
summary: Generate a new voice note
description: |
Generates a voice note based on the provided text and voice ID, returning an OGG file URL.
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
vid:
type: string
description: UUID of the voice.
example: "vid_6c859031-ed4c-4ed3-9134-6bdc6b69b90c"
text:
type: string
description: The text to be converted into a voice note.
example: "Hello, welcome to Callbook AI."
client_id:
type: string
description: UUID of the client requesting the voice note.
example: "ac8238ec-1689-40d0-8bd8-18af6141f5f5"
responses:
"200":
description: Successfully generated the voice note.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The unique identifier of the generated voice note.
example: "vn_123456789"
path:
type: string
description: URL to the generated voice note.
example: "https://s3.amazonaws.com/voice_notes/vn_123456789.ogg"
duration:
type: integer
description: Duration of the generated voice note in seconds.
example: 10
client_id:
type: string
description: The client ID associated with the request.
example: "ac8238ec-1689-40d0-8bd8-18af6141f5f5"
"400":
description: Bad request (missing required fields).
"401":
description: Unauthorized (invalid or missing JWT token).
"500":
description: Internal server error.
/list_voices:
get:
tags:
- Voice Notes
summary: Retrieve available voices
description: |
Retrieves a list of available voices that can be used to generate voice notes.
responses:
"200":
description: Successfully retrieved the list of voices.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: "List of voices"
voices:
type: array
items:
type: object
properties:
country:
type: string
description: Country of the voice.
example: "MX"
gender:
type: string
description: Gender of the voice.
example: "female"
subDetail:
type: string
description: Additional details about the voice.
example: "1"
vid:
type: string
description: UUID of the voice.
example: "vid_6c859031-ed4c-4ed3-9134-6bdc6b69b90c"
"500":
description: Internal server error.
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT