Skip to main content
bidiDocs Dashboard

API reference

Chat

One guarded turn with an agent, as plain JSON or streamed as server-sent events, and the answers to client tools.

All endpoint groups

POST /agents/{agent_id}/chat

Chat with an agent

Send the visitor's message and get the agent's answer. With "stream": true the answer arrives as server-sent events (delta, sources, outcome, done, or error), the same events the website widget receives, with a : keep-alive comment line while the agent is thinking. A new conversation counts against the workspace's monthly conversations the moment it gets its first answer; when the month is full the agent answers with its capacity note and limit is monthly. Twenty chat calls per key per minute. Idempotency-Key is honoured on the plain call; a stream cannot be replayed, so a streamed call ignores it. With contact, a conversation proven to be one person's is never continued as another's: that call answers 409 identity_mismatch and no turn runs.

Scope: chat

Parameters

  • agent_id required in the path · string

Request body

  • messages required ChatMessage[]

    The last entry must be the visitor's new message (role user). Earlier entries are ignored when conversation_id is set: the stored conversation is the context.

  • conversation_id optional string

    Continue this conversation; omit to start one.

  • conversation_token optional string

    With a publishable key: the conversation_token the conversation's first answer gave. Required to continue it (the id alone answers 404 conversation_not_found), because a publishable key ships inside the app and conversation ids are not secret.

  • stream optional boolean

    true answers text/event-stream.

  • locale optional string

    Reserved: a hint for the reply language.

  • contact optional object

    Who the visitor is, in either identity shape: {"token": a JWT signed with the agent's identity secret} or {"user_id", "user_hash"}. Verified, it links the conversation to that contact (and its memory); one that does not verify answers 401 identity_rejected. A conversation proven to be one person's is never continued as another: send a different verified contact with its conversation_id and the call answers 409 identity_mismatch (omit conversation_id to start that person's own conversation).

  • client_tools optional string[]

    The client tools your app can run (snake_case names, up to 20). Only the owner's declared client tools among them are offered, and only on a streamed call: the agent asks with a client_tool event and your app answers on POST /agents/{agent_id}/chat/tool-results.

Returns ChatResponse

  • conversation_id required string

    Send it back to continue this conversation.

  • conversation_token optional string

    Publishable keys only, on the answer that starts a conversation: send it back with conversation_id to continue it. Shown once; keep it with the id.

  • message optional ChatMessageOut

    The agent's answer; null when a person has taken over.

  • outcome optional string

    Outcome

  • refused required boolean

    Refused

  • sources required []

    Sources

  • state optional string

    State

  • lead_captured required boolean

    Lead Captured

  • limit optional string

    monthly when the month's conversations are used up.

  • degraded required boolean

    Degraded

Responses

  • 200 The answer. application/json by default; text/event-stream when stream is true.
  • 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
  • 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
  • 404 Nothing by that id in this workspace.
  • 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
  • 422 The request did not validate; details lists the fields.
  • 429 Rate limit reached; wait Retry-After seconds.
  • 500 Our fault; quote request_id to support.
  • 409 agent_unavailable: the agent is paused. identity_mismatch: the conversation is another verified contact's; start a new one for this contact. idempotency_in_progress: the first request with this Idempotency-Key is still running.
  • 410 conversation_expired: the conversation is over; start a new one.
  • 503 identity_unavailable: the agent's identity secret cannot be read right now, so contact cannot be verified; retry after Retry-After seconds.
curl
curl -X POST https://www.bidii.ai/api/v2/agents/AGENT_ID/chat \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "..."}]}'

POST /agents/{agent_id}/chat/tool-results

Answer a client tool call

Your app ran the client tool a streamed chat asked for (the client_tool event) and says how it went. Only the conversation the call belongs to can answer it, once, before its timeout_ms; a second answer, or a late one, is 409 call_closed, and a call this conversation never had is 404 unknown_call. Needs the actions feature on the server (404 otherwise).

Scope: chat

Parameters

  • agent_id required in the path · string

Request body

  • conversation_id required string

    The conversation the client_tool event belongs to.

  • conversation_token optional string

    The event's conversation_token (publishable keys).

  • call_id required string

    The event's call_id.

  • ok required boolean

    false when your tool failed; the agent is told it did not work.

  • result optional object

    What the tool returned, as JSON (at most 8,000 characters). The agent reads it as data, never as instructions.

  • error optional string

    A short reason when ok is false (120 characters are kept).

Returns ChatToolResultOut

  • ok required boolean

    Ok

Responses

  • 200 Successful Response
  • 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
  • 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
  • 404 Nothing by that id in this workspace.
  • 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
  • 422 The request did not validate; details lists the fields.
  • 429 Rate limit reached; wait Retry-After seconds.
  • 500 Our fault; quote request_id to support.
  • 409 call_closed: the call was already answered or ran out of time.
curl
curl -X POST https://www.bidii.ai/api/v2/agents/AGENT_ID/chat/tool-results \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id": "...", "call_id": "...", "ok": true}'