# Create Chat Message

`POST /v1/chats/{chat_id}/messages`

Send a message and get the agent's reply back on this request.

A newer message supersedes one still being answered: the older request
returns `status: canceled` with `superseded_by_item_id`.

Authenticate with `Authorization: Bearer $TALQING_API_KEY`. Errors use the shared envelope: https://docs.talqing.com/api-reference/errors.md

## OpenAPI

```json
{
 "openapi":"3.1.0",
 "servers":[
  {
   "description":"Talqing API",
   "url":"https://api.talqing.com"
  }
 ],
 "paths":{
  "/v1/chats/{chat_id}/messages":{
   "post":{
    "description":"Send a message and get the agent's reply back on this request.\n\nA newer message supersedes one still being answered: the older request\nreturns `status: canceled` with `superseded_by_item_id`.",
    "operationId":"chats.messages.create",
    "parameters":[
     {
      "in":"path",
      "name":"chat_id",
      "required":true,
      "schema":{
       "format":"uuid",
       "title":"Chat Id",
       "type":"string"
      }
     }
    ],
    "requestBody":{
     "content":{
      "application/json":{
       "schema":{
        "$ref":"#/components/schemas/ChatMessageRequest"
       }
      }
     },
     "required":true
    },
    "responses":{
     "200":{
      "content":{
       "application/json":{
        "schema":{
         "$ref":"#/components/schemas/ChatTurnResponse"
        }
       },
       "text/event-stream":{
        "schema":{
         "discriminator":{
          "mapping":{
           "assistant.completed":"#/components/schemas/AssistantCompletedEvent",
           "assistant.delta":"#/components/schemas/AssistantDeltaEvent",
           "assistant.started":"#/components/schemas/AssistantStartedEvent",
           "item.created":"#/components/schemas/ItemCreatedEvent",
           "turn.result":"#/components/schemas/ChatTurnResultEvent"
          },
          "propertyName":"event"
         },
         "oneOf":[
          {
           "$ref":"#/components/schemas/AssistantStartedEvent"
          },
          {
           "$ref":"#/components/schemas/AssistantDeltaEvent"
          },
          {
           "$ref":"#/components/schemas/AssistantCompletedEvent"
          },
          {
           "$ref":"#/components/schemas/ItemCreatedEvent"
          },
          {
           "$ref":"#/components/schemas/ChatTurnResultEvent"
          }
         ]
        }
       }
      },
      "description":"The turn. With `stream: true`, a `text/event-stream` of `assistant.*` and `item.created` frames ending in one `turn.result`."
     },
     "400":{
      "$ref":"#/components/responses/BadRequest"
     },
     "401":{
      "$ref":"#/components/responses/Unauthorized"
     },
     "403":{
      "$ref":"#/components/responses/Forbidden"
     },
     "404":{
      "$ref":"#/components/responses/NotFound"
     },
     "409":{
      "$ref":"#/components/responses/Conflict"
     },
     "422":{
      "$ref":"#/components/responses/ValidationFailed"
     },
     "default":{
      "$ref":"#/components/responses/Error"
     }
    },
    "security":[
     {
      "BearerAuth":[]
     },
     {
      "SessionCookie":[]
     }
    ],
    "summary":"Create Chat Message",
    "tags":[
     "chats"
    ]
   }
  }
 },
 "components":{
  "responses":{
   "BadRequest":{
    "content":{
     "application/json":{
      "schema":{
       "$ref":"#/components/schemas/ErrorResponse"
      }
     }
    },
    "description":"Well-formed, but rejected by a rule; `detail.errors` lists each problem."
   },
   "Conflict":{
    "content":{
     "application/json":{
      "schema":{
       "$ref":"#/components/schemas/ErrorResponse"
      }
     }
    },
    "description":"The resource's current state forbids this \u2014 a name already taken, a job already running."
   },
   "Error":{
    "content":{
     "application/json":{
      "schema":{
       "$ref":"#/components/schemas/ErrorResponse"
      }
     }
    },
    "description":"Unexpected error. Every error this API returns carries this body."
   },
   "Forbidden":{
    "content":{
     "application/json":{
      "schema":{
       "$ref":"#/components/schemas/ErrorResponse"
      }
     }
    },
    "description":"Authenticated, but this organization role may not perform the operation."
   },
   "NotFound":{
    "content":{
     "application/json":{
      "schema":{
       "$ref":"#/components/schemas/ErrorResponse"
      }
     }
    },
    "description":"No such resource in this organization."
   },
   "Unauthorized":{
    "content":{
     "application/json":{
      "schema":{
       "$ref":"#/components/schemas/ErrorResponse"
      }
     }
    },
    "description":"Missing credential, or one that is revoked or no longer a member of this organization."
   },
   "ValidationFailed":{
    "content":{
     "application/json":{
      "schema":{
       "$ref":"#/components/schemas/ErrorResponse"
      }
     }
    },
    "description":"The request did not match this operation's schema; `detail.errors` lists each field."
   }
  },
  "schemas":{
   "AssistantCompletedEvent":{
    "description":"The reply is whole. `text` is every delta joined, so a client that missed\nsome can replace what it accumulated rather than reconcile it.",
    "properties":{
     "event":{
      "const":"assistant.completed",
      "default":"assistant.completed",
      "title":"Event",
      "type":"string"
     },
     "item_ids":{
      "items":{
       "format":"uuid",
       "type":"string"
      },
      "title":"Item Ids",
      "type":"array"
     },
     "session_id":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Session Id"
     },
     "text":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Text"
     },
     "trigger_item_id":{
      "format":"uuid",
      "title":"Trigger Item Id",
      "type":"string"
     }
    },
    "required":[
     "event",
     "trigger_item_id",
     "session_id",
     "text",
     "item_ids"
    ],
    "title":"AssistantCompletedEvent",
    "type":"object"
   },
   "AssistantDeltaEvent":{
    "description":"One chunk of the reply. Append; these are not cumulative.",
    "properties":{
     "event":{
      "const":"assistant.delta",
      "default":"assistant.delta",
      "title":"Event",
      "type":"string"
     },
     "text":{
      "title":"Text",
      "type":"string"
     },
     "trigger_item_id":{
      "format":"uuid",
      "title":"Trigger Item Id",
      "type":"string"
     }
    },
    "required":[
     "event",
     "trigger_item_id",
     "text"
    ],
    "title":"AssistantDeltaEvent",
    "type":"object"
   },
   "AssistantStartedEvent":{
    "description":"The reply has begun; `assistant.delta` frames follow.",
    "properties":{
     "event":{
      "const":"assistant.started",
      "default":"assistant.started",
      "title":"Event",
      "type":"string"
     },
     "trigger_item_id":{
      "format":"uuid",
      "title":"Trigger Item Id",
      "type":"string"
     }
    },
    "required":[
     "event",
     "trigger_item_id"
    ],
    "title":"AssistantStartedEvent",
    "type":"object"
   },
   "AttachmentNotKept":{
    "description":"A file the person sent that could not be stored.",
    "properties":{
     "reason":{
      "description":"Why, as a sentence for a person.",
      "title":"Reason",
      "type":"string"
     }
    },
    "required":[
     "reason"
    ],
    "title":"AttachmentNotKept",
    "type":"object"
   },
   "ButtonTap":{
    "properties":{
     "payload":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Payload"
     },
     "text":{
      "title":"Text",
      "type":"string"
     }
    },
    "required":[
     "text"
    ],
    "title":"ButtonTap",
    "type":"object"
   },
   "ChatMessageRequest":{
    "description":"One message: what was typed, what was attached, or both.",
    "properties":{
     "client_message_id":{
      "format":"uuid",
      "title":"Client Message Id",
      "type":"string"
     },
     "files":{
      "description":"Any type; photos, PDFs and Word files are read by the agent.",
      "items":{
       "$ref":"#/components/schemas/InboundFile"
      },
      "maxItems":4,
      "title":"Files",
      "type":"array"
     },
     "message":{
      "default":"",
      "maxLength":100000,
      "title":"Message",
      "type":"string"
     },
     "stream":{
      "default":false,
      "title":"Stream",
      "type":"boolean"
     }
    },
    "required":[
     "client_message_id"
    ],
    "title":"ChatMessageRequest",
    "type":"object"
   },
   "ChatTurnResponse":{
    "description":"What one message led to: the agent's reply, and where the chat stands.",
    "properties":{
     "chat_status":{
      "enum":[
       "open",
       "ended"
      ],
      "title":"Chat Status",
      "type":"string"
     },
     "error":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Error"
     },
     "input":{
      "$ref":"#/components/schemas/ConversationItemResponse"
     },
     "items":{
      "items":{
       "$ref":"#/components/schemas/ConversationItemResponse"
      },
      "title":"Items",
      "type":"array"
     },
     "status":{
      "enum":[
       "running",
       "done",
       "error",
       "canceled"
      ],
      "title":"Status",
      "type":"string"
     },
     "superseded_by_item_id":{
      "anyOf":[
       {
        "format":"uuid",
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Superseded By Item Id"
     }
    },
    "required":[
     "input",
     "status",
     "error",
     "superseded_by_item_id",
     "items",
     "chat_status"
    ],
    "title":"ChatTurnResponse",
    "type":"object"
   },
   "ChatTurnResultEvent":{
    "description":"The last frame of a streamed turn, carrying what the JSON response would.",
    "properties":{
     "chat_status":{
      "enum":[
       "open",
       "ended"
      ],
      "title":"Chat Status",
      "type":"string"
     },
     "error":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Error"
     },
     "event":{
      "const":"turn.result",
      "default":"turn.result",
      "title":"Event",
      "type":"string"
     },
     "input":{
      "$ref":"#/components/schemas/ConversationItemResponse"
     },
     "items":{
      "items":{
       "$ref":"#/components/schemas/ConversationItemResponse"
      },
      "title":"Items",
      "type":"array"
     },
     "status":{
      "enum":[
       "running",
       "done",
       "error",
       "canceled"
      ],
      "title":"Status",
      "type":"string"
     },
     "superseded_by_item_id":{
      "anyOf":[
       {
        "format":"uuid",
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Superseded By Item Id"
     }
    },
    "required":[
     "input",
     "status",
     "error",
     "superseded_by_item_id",
     "items",
     "chat_status",
     "event"
    ],
    "title":"ChatTurnResultEvent",
    "type":"object"
   },
   "ContactCard":{
    "description":"One card in a shared contact file.",
    "properties":{
     "emails":{
      "items":{
       "type":"string"
      },
      "title":"Emails",
      "type":"array"
     },
     "name":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Name"
     },
     "organization":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Organization"
     },
     "phones":{
      "items":{
       "type":"string"
      },
      "title":"Phones",
      "type":"array"
     }
    },
    "required":[
     "name",
     "phones",
     "emails",
     "organization"
    ],
    "title":"ContactCard",
    "type":"object"
   },
   "ConversationAudio":{
    "description":"A voice note or audio file the person sent, and what they said in it.",
    "properties":{
     "bytes":{
      "title":"Bytes",
      "type":"integer"
     },
     "duration_seconds":{
      "anyOf":[
       {
        "type":"number"
       },
       {
        "type":"null"
       }
      ],
      "title":"Duration Seconds"
     },
     "extension":{
      "description":"The type read from its bytes, e.g. `ogg` or `m4a`.",
      "title":"Extension",
      "type":"string"
     },
     "failed_reason":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "description":"Why it could not be transcribed.",
      "title":"Failed Reason"
     },
     "filename":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Filename"
     },
     "id":{
      "format":"uuid",
      "title":"Id",
      "type":"string"
     },
     "kind":{
      "const":"audio",
      "default":"audio",
      "title":"Kind",
      "type":"string"
     },
     "mime_type":{
      "title":"Mime Type",
      "type":"string"
     },
     "playable":{
      "description":"Whether `url` plays in an `<audio>` element.",
      "title":"Playable",
      "type":"boolean"
     },
     "status":{
      "description":"`pending` until an agent with a speech-to-text model takes a turn.",
      "enum":[
       "pending",
       "transcribed",
       "failed"
      ],
      "title":"Status",
      "type":"string"
     },
     "transcript":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "description":"What was said; empty when there was no speech.",
      "title":"Transcript"
     },
     "url":{
      "description":"Signed link; valid until `url_expires_at`.",
      "title":"Url",
      "type":"string"
     },
     "url_expires_at":{
      "format":"date-time",
      "title":"Url Expires At",
      "type":"string"
     }
    },
    "required":[
     "id",
     "mime_type",
     "extension",
     "playable",
     "bytes",
     "filename",
     "status",
     "duration_seconds",
     "transcript",
     "failed_reason",
     "url",
     "url_expires_at"
    ],
    "title":"ConversationAudio",
    "type":"object"
   },
   "ConversationContact":{
    "description":"A contact card the person shared, as read from the vCard.",
    "properties":{
     "bytes":{
      "title":"Bytes",
      "type":"integer"
     },
     "contacts":{
      "description":"One per card in the file.",
      "items":{
       "$ref":"#/components/schemas/ContactCard"
      },
      "title":"Contacts",
      "type":"array"
     },
     "filename":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Filename"
     },
     "id":{
      "format":"uuid",
      "title":"Id",
      "type":"string"
     },
     "kind":{
      "const":"contact",
      "default":"contact",
      "title":"Kind",
      "type":"string"
     },
     "mime_type":{
      "const":"text/vcard",
      "default":"text/vcard",
      "title":"Mime Type",
      "type":"string"
     },
     "url":{
      "description":"Signed download of the .vcf; valid until `url_expires_at`.",
      "title":"Url",
      "type":"string"
     },
     "url_expires_at":{
      "format":"date-time",
      "title":"Url Expires At",
      "type":"string"
     }
    },
    "required":[
     "id",
     "bytes",
     "filename",
     "contacts",
     "url",
     "url_expires_at"
    ],
    "title":"ConversationContact",
    "type":"object"
   },
   "ConversationDocument":{
    "description":"A PDF or Word file the person sent, and whether the agent could read it.",
    "properties":{
     "bytes":{
      "title":"Bytes",
      "type":"integer"
     },
     "filename":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Filename"
     },
     "id":{
      "format":"uuid",
      "title":"Id",
      "type":"string"
     },
     "kind":{
      "const":"document",
      "default":"document",
      "title":"Kind",
      "type":"string"
     },
     "mime_type":{
      "title":"Mime Type",
      "type":"string"
     },
     "pages":{
      "anyOf":[
       {
        "type":"integer"
       },
       {
        "type":"null"
       }
      ],
      "description":"A PDF's page count; null for Word files.",
      "title":"Pages"
     },
     "status":{
      "description":"`pending` until the agent's next turn reads it.",
      "enum":[
       "pending",
       "read",
       "unreadable"
      ],
      "title":"Status",
      "type":"string"
     },
     "unreadable_reason":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "description":"Why the agent could not read it.",
      "title":"Unreadable Reason"
     },
     "url":{
      "description":"Signed download link; valid until `url_expires_at`.",
      "title":"Url",
      "type":"string"
     },
     "url_expires_at":{
      "format":"date-time",
      "title":"Url Expires At",
      "type":"string"
     }
    },
    "required":[
     "id",
     "mime_type",
     "bytes",
     "filename",
     "status",
     "pages",
     "unreadable_reason",
     "url",
     "url_expires_at"
    ],
    "title":"ConversationDocument",
    "type":"object"
   },
   "ConversationFile":{
    "description":"Any other file the person sent, stored for you; the agent cannot open it.",
    "properties":{
     "bytes":{
      "title":"Bytes",
      "type":"integer"
     },
     "extension":{
      "description":"The type read from its bytes, e.g. `xlsx`; `bin` if unknown.",
      "title":"Extension",
      "type":"string"
     },
     "filename":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Filename"
     },
     "id":{
      "format":"uuid",
      "title":"Id",
      "type":"string"
     },
     "kind":{
      "const":"file",
      "default":"file",
      "title":"Kind",
      "type":"string"
     },
     "mime_type":{
      "title":"Mime Type",
      "type":"string"
     },
     "playable":{
      "anyOf":[
       {
        "const":"video",
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "description":"Set when `url` plays in a `<video>` element.",
      "title":"Playable"
     },
     "url":{
      "description":"Signed link; valid until `url_expires_at`.",
      "title":"Url",
      "type":"string"
     },
     "url_expires_at":{
      "format":"date-time",
      "title":"Url Expires At",
      "type":"string"
     }
    },
    "required":[
     "id",
     "mime_type",
     "extension",
     "playable",
     "bytes",
     "filename",
     "url",
     "url_expires_at"
    ],
    "title":"ConversationFile",
    "type":"object"
   },
   "ConversationImage":{
    "description":"A photo the person sent, with a short-lived link to it.",
    "properties":{
     "bytes":{
      "title":"Bytes",
      "type":"integer"
     },
     "filename":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Filename"
     },
     "height":{
      "title":"Height",
      "type":"integer"
     },
     "id":{
      "format":"uuid",
      "title":"Id",
      "type":"string"
     },
     "kind":{
      "const":"image",
      "default":"image",
      "title":"Kind",
      "type":"string"
     },
     "mime_type":{
      "title":"Mime Type",
      "type":"string"
     },
     "url":{
      "description":"Signed; valid until `url_expires_at`.",
      "title":"Url",
      "type":"string"
     },
     "url_expires_at":{
      "format":"date-time",
      "title":"Url Expires At",
      "type":"string"
     },
     "width":{
      "title":"Width",
      "type":"integer"
     }
    },
    "required":[
     "id",
     "mime_type",
     "bytes",
     "width",
     "height",
     "url",
     "url_expires_at"
    ],
    "title":"ConversationImage",
    "type":"object"
   },
   "ConversationItemResponse":{
    "properties":{
     "agent_id":{
      "anyOf":[
       {
        "format":"uuid",
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Agent Id"
     },
     "agent_version":{
      "anyOf":[
       {
        "type":"integer"
       },
       {
        "const":"draft",
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Agent Version"
     },
     "attachments":{
      "items":{
       "discriminator":{
        "mapping":{
         "audio":"#/components/schemas/ConversationAudio",
         "contact":"#/components/schemas/ConversationContact",
         "document":"#/components/schemas/ConversationDocument",
         "file":"#/components/schemas/ConversationFile",
         "image":"#/components/schemas/ConversationImage"
        },
        "propertyName":"kind"
       },
       "oneOf":[
        {
         "$ref":"#/components/schemas/ConversationImage"
        },
        {
         "$ref":"#/components/schemas/ConversationDocument"
        },
        {
         "$ref":"#/components/schemas/ConversationAudio"
        },
        {
         "$ref":"#/components/schemas/ConversationContact"
        },
        {
         "$ref":"#/components/schemas/ConversationFile"
        }
       ]
      },
      "title":"Attachments",
      "type":"array"
     },
     "attachments_not_kept":{
      "description":"Files the person sent that could not be stored.",
      "items":{
       "$ref":"#/components/schemas/AttachmentNotKept"
      },
      "title":"Attachments Not Kept",
      "type":"array"
     },
     "author":{
      "anyOf":[
       {
        "$ref":"#/components/schemas/ItemAuthor"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "description":"Who at your business posted this."
     },
     "channel":{
      "anyOf":[
       {
        "enum":[
         "phone_call",
         "whatsapp_call",
         "whatsapp_message",
         "web_call",
         "chat",
         "telegram",
         "stream",
         "copilot"
        ],
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "description":"How this item reached us or the person; null for notes and instructions.",
      "title":"Channel"
     },
     "client_message_id":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Client Message Id"
     },
     "content":{
      "anyOf":[
       {
        "$ref":"#/components/schemas/InboundContent"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "description":"What the person sent besides text; null for plain text."
     },
     "conversation_id":{
      "format":"uuid",
      "title":"Conversation Id",
      "type":"string"
     },
     "created_at":{
      "format":"date-time",
      "title":"Created At",
      "type":"string"
     },
     "delivery_error":{
      "anyOf":[
       {
        "$ref":"#/components/schemas/DeliveryError"
       },
       {
        "type":"null"
       }
      ],
      "default":null
     },
     "delivery_status":{
      "enum":[
       "not_applicable",
       "pending",
       "held",
       "sending",
       "queued",
       "sent",
       "delivered",
       "read",
       "undelivered",
       "failed",
       "skipped",
       "expired"
      ],
      "title":"Delivery Status",
      "type":"string"
     },
     "direction":{
      "enum":[
       "inbound",
       "outbound",
       "internal"
      ],
      "title":"Direction",
      "type":"string"
     },
     "elapsed":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Elapsed"
     },
     "id":{
      "format":"uuid",
      "title":"Id",
      "type":"string"
     },
     "idempotency_key":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Idempotency Key"
     },
     "latency":{
      "anyOf":[
       {
        "$ref":"#/components/schemas/ReplyLatency"
       },
       {
        "type":"null"
       }
      ],
      "default":null
     },
     "metadata":{
      "additionalProperties":true,
      "title":"Metadata",
      "type":"object"
     },
     "metrics":{
      "anyOf":[
       {
        "$ref":"#/components/schemas/TurnMetrics"
       },
       {
        "type":"null"
       }
      ],
      "default":null
     },
     "origin":{
      "anyOf":[
       {
        "enum":[
         "speech",
         "typed",
         "keypad"
        ],
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Origin"
     },
     "post_type":{
      "anyOf":[
       {
        "enum":[
         "template",
         "agent_text",
         "note",
         "instruction"
        ],
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "description":"What was posted through the API; null for everything else.",
      "title":"Post Type"
     },
     "provider_message_id":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Provider Message Id"
     },
     "raw_payload":{
      "anyOf":[
       {
        "additionalProperties":true,
        "type":"object"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Raw Payload"
     },
     "role":{
      "anyOf":[
       {
        "enum":[
         "developer",
         "system",
         "user",
         "assistant",
         "tool"
        ],
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Role"
     },
     "scope":{
      "enum":[
       "conversation",
       "turn"
      ],
      "title":"Scope",
      "type":"string"
     },
     "session_id":{
      "anyOf":[
       {
        "format":"uuid",
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Session Id"
     },
     "text":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Text"
     },
     "trigger_item_id":{
      "anyOf":[
       {
        "format":"uuid",
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Trigger Item Id"
     },
     "turn_error":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Turn Error"
     },
     "turn_status":{
      "anyOf":[
       {
        "enum":[
         "running",
         "done",
         "error",
         "canceled"
        ],
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Turn Status"
     },
     "type":{
      "enum":[
       "message",
       "function_call",
       "function_call_output",
       "agent_handoff",
       "agent_config_update"
      ],
      "title":"Type",
      "type":"string"
     },
     "updated_at":{
      "format":"date-time",
      "title":"Updated At",
      "type":"string"
     },
     "visibility":{
      "enum":[
       "customer_visible",
       "internal"
      ],
      "title":"Visibility",
      "type":"string"
     }
    },
    "required":[
     "id",
     "conversation_id",
     "session_id",
     "trigger_item_id",
     "direction",
     "type",
     "role",
     "agent_id",
     "agent_version",
     "text",
     "attachments",
     "attachments_not_kept",
     "content",
     "provider_message_id",
     "client_message_id",
     "delivery_status",
     "delivery_error",
     "turn_status",
     "turn_error",
     "channel",
     "post_type",
     "author",
     "idempotency_key",
     "visibility",
     "scope",
     "metrics",
     "origin",
     "elapsed",
     "latency",
     "metadata",
     "raw_payload",
     "created_at",
     "updated_at"
    ],
    "title":"ConversationItemResponse",
    "type":"object"
   },
   "DeliveryError":{
    "description":"Outbound delivery failure detail (provider HTTP / shadow-mode skips).\n\nWriters always store `{\"message\": ...}`, plus the provider's `code` when it\ngave one (see services.messaging.delivery).",
    "properties":{
     "code":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "description":"The provider's error code, if any.",
      "title":"Code"
     },
     "message":{
      "title":"Message",
      "type":"string"
     }
    },
    "required":[
     "message",
     "code"
    ],
    "title":"DeliveryError",
    "type":"object"
   },
   "ErrorBody":{
    "description":"The structured half of our error contract: a human `message` plus a list\nof individual `errors` (used wherever we surface many problems at once,\nincluding tool publish, op-tree checks, and request validation). The global\nexception handlers normalize every API error to\n`{detail: {message, errors, code}}`, so SDKs can parse one shape consistently.",
    "properties":{
     "code":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "description":"A stable identifier for this error, when it has one.",
      "title":"Code"
     },
     "errors":{
      "items":{
       "type":"string"
      },
      "title":"Errors",
      "type":"array"
     },
     "message":{
      "title":"Message",
      "type":"string"
     }
    },
    "required":[
     "message",
     "errors"
    ],
    "title":"ErrorBody",
    "type":"object"
   },
   "ErrorResponse":{
    "description":"The body of every error response, at every status code.",
    "properties":{
     "detail":{
      "$ref":"#/components/schemas/ErrorBody"
     }
    },
    "required":[
     "detail"
    ],
    "title":"ErrorResponse",
    "type":"object"
   },
   "InboundContent":{
    "description":"What the person sent besides text.",
    "properties":{
     "button":{
      "$ref":"#/components/schemas/ButtonTap"
     },
     "kind":{
      "const":"button",
      "title":"Kind",
      "type":"string"
     },
     "replied_to":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "description":"Provider id of the message this answers, e.g. the template.",
      "title":"Replied To"
     }
    },
    "required":[
     "kind",
     "button"
    ],
    "title":"InboundContent",
    "type":"object"
   },
   "InboundFile":{
    "description":"One file on an inbound text message: the bytes, and what to call them.",
    "properties":{
     "data_url":{
      "description":"`data:<mime>;base64,<bytes>`, up to 20 MB decoded.",
      "minLength":1,
      "title":"Data Url",
      "type":"string"
     },
     "filename":{
      "anyOf":[
       {
        "maxLength":255,
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Filename"
     }
    },
    "required":[
     "data_url"
    ],
    "title":"InboundFile",
    "type":"object"
   },
   "ItemAuthor":{
    "additionalProperties":false,
    "description":"Who at your business posted an item.",
    "properties":{
     "id":{
      "maxLength":128,
      "minLength":1,
      "title":"Id",
      "type":"string"
     },
     "name":{
      "maxLength":128,
      "minLength":1,
      "title":"Name",
      "type":"string"
     }
    },
    "required":[
     "id",
     "name"
    ],
    "title":"ItemAuthor",
    "type":"object"
   },
   "ItemCreatedEvent":{
    "description":"One new item, in the same shape `list_conversation_items` returns it.",
    "properties":{
     "agent_id":{
      "anyOf":[
       {
        "format":"uuid",
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Agent Id"
     },
     "agent_version":{
      "anyOf":[
       {
        "type":"integer"
       },
       {
        "const":"draft",
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Agent Version"
     },
     "attachments":{
      "items":{
       "discriminator":{
        "mapping":{
         "audio":"#/components/schemas/ConversationAudio",
         "contact":"#/components/schemas/ConversationContact",
         "document":"#/components/schemas/ConversationDocument",
         "file":"#/components/schemas/ConversationFile",
         "image":"#/components/schemas/ConversationImage"
        },
        "propertyName":"kind"
       },
       "oneOf":[
        {
         "$ref":"#/components/schemas/ConversationImage"
        },
        {
         "$ref":"#/components/schemas/ConversationDocument"
        },
        {
         "$ref":"#/components/schemas/ConversationAudio"
        },
        {
         "$ref":"#/components/schemas/ConversationContact"
        },
        {
         "$ref":"#/components/schemas/ConversationFile"
        }
       ]
      },
      "title":"Attachments",
      "type":"array"
     },
     "attachments_not_kept":{
      "description":"Files the person sent that could not be stored.",
      "items":{
       "$ref":"#/components/schemas/AttachmentNotKept"
      },
      "title":"Attachments Not Kept",
      "type":"array"
     },
     "author":{
      "anyOf":[
       {
        "$ref":"#/components/schemas/ItemAuthor"
       },
       {
        "type":"null"
       }
      ],
      "description":"Who at your business posted this."
     },
     "channel":{
      "anyOf":[
       {
        "enum":[
         "phone_call",
         "whatsapp_call",
         "whatsapp_message",
         "web_call",
         "chat",
         "telegram",
         "stream",
         "copilot"
        ],
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "description":"How this item reached us or the person; null for notes and instructions.",
      "title":"Channel"
     },
     "client_message_id":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Client Message Id"
     },
     "content":{
      "anyOf":[
       {
        "$ref":"#/components/schemas/InboundContent"
       },
       {
        "type":"null"
       }
      ],
      "description":"What the person sent besides text; null for plain text."
     },
     "conversation_id":{
      "format":"uuid",
      "title":"Conversation Id",
      "type":"string"
     },
     "created_at":{
      "format":"date-time",
      "title":"Created At",
      "type":"string"
     },
     "delivery_error":{
      "anyOf":[
       {
        "$ref":"#/components/schemas/DeliveryError"
       },
       {
        "type":"null"
       }
      ]
     },
     "delivery_status":{
      "enum":[
       "not_applicable",
       "pending",
       "held",
       "sending",
       "queued",
       "sent",
       "delivered",
       "read",
       "undelivered",
       "failed",
       "skipped",
       "expired"
      ],
      "title":"Delivery Status",
      "type":"string"
     },
     "direction":{
      "enum":[
       "inbound",
       "outbound",
       "internal"
      ],
      "title":"Direction",
      "type":"string"
     },
     "elapsed":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Elapsed"
     },
     "event":{
      "const":"item.created",
      "default":"item.created",
      "title":"Event",
      "type":"string"
     },
     "id":{
      "format":"uuid",
      "title":"Id",
      "type":"string"
     },
     "idempotency_key":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Idempotency Key"
     },
     "latency":{
      "anyOf":[
       {
        "$ref":"#/components/schemas/ReplyLatency"
       },
       {
        "type":"null"
       }
      ]
     },
     "metadata":{
      "additionalProperties":true,
      "title":"Metadata",
      "type":"object"
     },
     "metrics":{
      "anyOf":[
       {
        "$ref":"#/components/schemas/TurnMetrics"
       },
       {
        "type":"null"
       }
      ]
     },
     "origin":{
      "anyOf":[
       {
        "enum":[
         "speech",
         "typed",
         "keypad"
        ],
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Origin"
     },
     "post_type":{
      "anyOf":[
       {
        "enum":[
         "template",
         "agent_text",
         "note",
         "instruction"
        ],
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "description":"What was posted through the API; null for everything else.",
      "title":"Post Type"
     },
     "provider_message_id":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Provider Message Id"
     },
     "raw_payload":{
      "anyOf":[
       {
        "additionalProperties":true,
        "type":"object"
       },
       {
        "type":"null"
       }
      ],
      "title":"Raw Payload"
     },
     "role":{
      "anyOf":[
       {
        "enum":[
         "developer",
         "system",
         "user",
         "assistant",
         "tool"
        ],
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Role"
     },
     "scope":{
      "enum":[
       "conversation",
       "turn"
      ],
      "title":"Scope",
      "type":"string"
     },
     "session_id":{
      "anyOf":[
       {
        "format":"uuid",
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Session Id"
     },
     "text":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Text"
     },
     "trigger_item_id":{
      "anyOf":[
       {
        "format":"uuid",
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Trigger Item Id"
     },
     "turn_error":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Turn Error"
     },
     "turn_status":{
      "anyOf":[
       {
        "enum":[
         "running",
         "done",
         "error",
         "canceled"
        ],
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Turn Status"
     },
     "type":{
      "enum":[
       "message",
       "function_call",
       "function_call_output",
       "agent_handoff",
       "agent_config_update"
      ],
      "title":"Type",
      "type":"string"
     },
     "updated_at":{
      "format":"date-time",
      "title":"Updated At",
      "type":"string"
     },
     "visibility":{
      "enum":[
       "customer_visible",
       "internal"
      ],
      "title":"Visibility",
      "type":"string"
     }
    },
    "required":[
     "id",
     "conversation_id",
     "session_id",
     "trigger_item_id",
     "direction",
     "type",
     "role",
     "agent_id",
     "agent_version",
     "text",
     "attachments",
     "attachments_not_kept",
     "content",
     "provider_message_id",
     "client_message_id",
     "delivery_status",
     "delivery_error",
     "turn_status",
     "turn_error",
     "channel",
     "post_type",
     "author",
     "idempotency_key",
     "visibility",
     "scope",
     "metrics",
     "origin",
     "elapsed",
     "latency",
     "metadata",
     "raw_payload",
     "created_at",
     "updated_at",
     "event"
    ],
    "title":"ItemCreatedEvent",
    "type":"object"
   },
   "LatencyStage":{
    "description":"One leg of a wait: what the time went on.",
    "properties":{
     "kind":{
      "enum":[
       "stt",
       "endpoint",
       "hook",
       "llm_step",
       "tool",
       "llm",
       "first_sentence",
       "tts",
       "other"
      ],
      "title":"Kind",
      "type":"string"
     },
     "label":{
      "title":"Label",
      "type":"string"
     },
     "ms":{
      "title":"Ms",
      "type":"number"
     }
    },
    "required":[
     "kind",
     "ms",
     "label"
    ],
    "title":"LatencyStage",
    "type":"object"
   },
   "ModelMetadata":{
    "additionalProperties":true,
    "description":"Which model a metrics sample came from.",
    "properties":{
     "model_name":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Model Name"
     },
     "model_provider":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Model Provider"
     }
    },
    "title":"ModelMetadata",
    "type":"object"
   },
   "ReplyLatency":{
    "description":"How long the caller waited for this reply, in the order it was spent.",
    "properties":{
     "kind":{
      "enum":[
       "response",
       "reply",
       "after_filler"
      ],
      "title":"Kind",
      "type":"string"
     },
     "stages":{
      "items":{
       "$ref":"#/components/schemas/LatencyStage"
      },
      "title":"Stages",
      "type":"array"
     },
     "total_ms":{
      "title":"Total Ms",
      "type":"number"
     }
    },
    "required":[
     "kind",
     "total_ms",
     "stages"
    ],
    "title":"ReplyLatency",
    "type":"object"
   },
   "TurnMetrics":{
    "additionalProperties":true,
    "description":"LiveKit MetricsReport samples for one transcript row, in seconds.\n\nEvery field is optional and unknown keys are kept: LiveKit owns this bag,\nso a version of it that reports something new must not fail a transcript\nwrite. What is named here is what the platform reads \u2014 the rest rides along\nverbatim.\n\nWhich fields are present depends on the row: `transcription_delay` and\n`end_of_turn_delay` are measured on the caller's message, the rest on the\nreply that closed the turn.",
    "properties":{
     "e2e_latency":{
      "anyOf":[
       {
        "type":"number"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"E2E Latency"
     },
     "end_of_turn_delay":{
      "anyOf":[
       {
        "type":"number"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"End Of Turn Delay"
     },
     "llm_metadata":{
      "anyOf":[
       {
        "$ref":"#/components/schemas/ModelMetadata"
       },
       {
        "type":"null"
       }
      ],
      "default":null
     },
     "llm_node_ttft":{
      "anyOf":[
       {
        "type":"number"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Llm Node Ttft"
     },
     "llm_tokens_per_second":{
      "anyOf":[
       {
        "type":"number"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Llm Tokens Per Second"
     },
     "on_user_turn_completed_delay":{
      "anyOf":[
       {
        "type":"number"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"On User Turn Completed Delay"
     },
     "started_speaking_at":{
      "anyOf":[
       {
        "type":"number"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Started Speaking At"
     },
     "stopped_speaking_at":{
      "anyOf":[
       {
        "type":"number"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Stopped Speaking At"
     },
     "stt_metadata":{
      "anyOf":[
       {
        "$ref":"#/components/schemas/ModelMetadata"
       },
       {
        "type":"null"
       }
      ],
      "default":null
     },
     "transcription_delay":{
      "anyOf":[
       {
        "type":"number"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Transcription Delay"
     },
     "tts_metadata":{
      "anyOf":[
       {
        "$ref":"#/components/schemas/ModelMetadata"
       },
       {
        "type":"null"
       }
      ],
      "default":null
     },
     "tts_node_ttfb":{
      "anyOf":[
       {
        "type":"number"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "title":"Tts Node Ttfb"
     }
    },
    "title":"TurnMetrics",
    "type":"object"
   }
  }
 }
}
```