AI Message¶

Message¶

{
    "id": "<string>",
    "customer_id": "<string>",
    "aicall_id": "<string>",
    "activeflow_id": "<string>",
    "active_ai_id": "<string>",
    "role": "<string>",
    "content": "<string>",
    "direction": "<string>",
    "origin": "<string>",
    "tool_calls": [],
    "tool_call_id": "<string>",
    "tm_create": "<string>"
}

id (UUID): The message’s unique identifier. Returned when listing via GET /ai-messages.
customer_id (UUID): The customer who owns this message. Obtained from the id field of GET /customers.
aicall_id (UUID): The AI call session this message belongs to. Obtained from the id field of GET /aicalls.
activeflow_id (UUID): The ID of the active flow associated with this message. Obtained from the id field of GET /activeflows. Set to 00000000-0000-0000-0000-000000000000 if no active flow.
active_ai_id (UUID): The ID of the AI configuration that was active when this message was created. Obtained from the id field of GET /ais. Set to 00000000-0000-0000-0000-000000000000 if no active AI.
role (enum string): The role of the message sender. See Role.
content (string): The text content of the message.
direction (enum string): The direction of the message. See Direction.
origin (enum string): How this message came to exist, orthogonally to role. See Origin.
tool_calls (array of ToolCall): Tool/function calls requested by the AI assistant. Each entry contains the tool name and arguments. Empty array if no tool calls.
tool_call_id (string): The ID of the tool call this message is responding to (for tool role messages only). Empty string if not a tool response.
tm_create (string, ISO 8601): Timestamp when this message was created.

Role¶

All possible values for the role field:

Role	Description
system	A system prompt or instruction
user	A message from the human user (transcribed speech or typed text)
assistant	A response generated by the AI model
function	A function call result (legacy, use `tool` instead)
tool	A tool/function call result
notification	A system notification message. `content` is a JSON object with a `type` field (see Notification content)

Direction¶

All possible values for the direction field:

Direction	Description
incoming	Message received from the user
outgoing	Message generated by the AI and sent to the user

Origin¶

All possible values for the origin field:

Origin	Description
(empty)	An ordinary message: an answer, or a question
proactive	A note the Insight Assistant sent on its own initiative while monitoring a live call, rather than in answer to anything
listen_internal	Internal bookkeeping produced while monitoring a live call. Do not depend on the presence or meaning of these messages

Notification content¶

A message with role notification records a session event rather than conversation text. Its content is a JSON object whose type field tells what happened. Notification messages are never sent to the AI model as conversation context. New type values may be added; ignore types you do not recognize.

member_switched: an AI team handed the conversation to another member.

pipeline_error: an AI service provider (language model, speech-to-text or text-to-speech) returned an error while the AI was handling the session, so the AI may not have answered.

{
    "type": "pipeline_error",
    "category": "authentication",
    "fatal": false,
    "pipecatcall_id": "9c5c6e64-6289-4ac9-ad88-b20796a6bc96",
    "message": "An AI service provider rejected the credentials or denied access. If this AI uses a custom engine key, verify that the key is valid and permitted for the selected model."
}

The message of the other categories is fixed text as well. For the connection category it is: The AI language model could not be reached. If this AI uses a custom base URL, verify that the address is correct and reachable over HTTPS.

category (enum string): The failure class.

Category	Description
authentication	The provider rejected the credentials or denied access. If the AI has a custom `engine_key`, check that it is valid and allowed to use the selected model.
rate_limited	The provider rejected the request because of a rate limit or quota.
timeout	The language model did not respond in time. It is also recorded when an AI chat on a case (contact case) is stopped after its time limit while the last message is still unanswered; this timeout is recorded once per AI call within 10 minutes and not at all if an error notice already exists for the same turn.
connection	The language model could not be reached: the connection was refused or broken, the address could not be resolved or is not allowed, or the server certificate is not valid. This category applies to every OpenAI-compatible language model provider, and it is the one to check first for an AI that uses a custom `engine_base_url`.
not_found	The language model or its endpoint was not found (the server answered 404). Check the model name, and the address and path of a custom `engine_base_url`. Applies to OpenAI-compatible language model providers.
server_error	The language model provider answered with a server error (status 500 to 599). Try again later. Applies to OpenAI-compatible language model providers.
stream_interrupted	The connection to the language model was interrupted while the answer was being received. Try again. Applies to OpenAI-compatible language model providers.
unknown	Any other provider error. For voice calls, only errors that stop the AI session are reported with this category.

fatal (boolean): true if the error stopped the AI session.
pipecatcall_id (UUID): Internal identifier of the AI processing turn that failed. Useful when contacting support.
message (string): A plain-text, human-readable description of the failure class. It does not contain the provider’s raw error text.

Each failing turn normally produces at most one pipeline_error message per category; in rare cases (event redelivery) a notice can be duplicated. For a voice call, the notice is recorded on the AI call only; the caller does not hear it.

Example¶

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "aicall_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "activeflow_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "active_ai_id": "d4e5f6a7-b8c9-0123-def4-56789abcdef1",
    "role": "user",
    "content": "I would like to transfer to the sales department.",
    "direction": "incoming",
    "tool_calls": [],
    "tool_call_id": "",
    "tm_create": "2024-03-01T10:00:05.000000Z"
}