Skip to main content
bidiDocs Dashboard

API reference

Conversations

What visitors and the API said, with outcomes, sources and campaigns.

All endpoint groups

GET /agents/{agent_id}/conversations

List an agent's conversations

Conversations of the agent, newest first, across every channel (the website widget, the hosted page, the API, email, Slack and voice). Filter by state and channel; page with cursor.

Scope: conversations:read

Parameters

  • agent_id required in the path · string
  • limit optional in the query · integer

    Rows per page, 1 to 100.

  • cursor optional in the query · string

    The next_cursor of the previous page.

  • state optional in the query · "ai_active" | "handoff_requested" | "human_active" | "closed"

    Only conversations in this state.

  • channel optional in the query · "website" | "hosted" | "api" | "email" | "slack" | "voice_web"

    Only conversations on this channel: website (the chat bubble on a site), hosted (the chat page), api, email, slack or voice_web.

Returns Conversation

  • id required string

    Id

  • agent_id required string

    Agent Id

  • channel required string

    website, hosted (the hosted chat page), api, email, slack or voice_web (a browser voice session). The same words as the dashboard's conversation log and the webhooks.

  • state required string

    ai_active, handoff_requested, human_active or closed.

  • started_at required string

    Started At

  • last_message_at optional string

    Last Message At

  • expires_at required string

    Expires At

  • lead_captured required boolean

    Lead Captured

  • summary optional string

    Summary

  • page_url optional string

    Page Url

  • utm optional object

    The campaign that brought the visitor: any of utm_source, utm_medium, utm_campaign, utm_term and utm_content, as the first page of the visit carried them. Empty when there was none.

  • referrer optional string

    The site that sent the visitor (scheme, host and path, never the query string). Empty when there was none.

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.
curl
curl https://www.bidii.ai/api/v2/agents/AGENT_ID/conversations \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"

GET /conversations/{conversation_id}

Get a conversation

One conversation: its state, timestamps and the summary the inbox shows.

Scope: conversations:read

Parameters

  • conversation_id required in the path · string

Returns Conversation

  • id required string

    Id

  • agent_id required string

    Agent Id

  • channel required string

    website, hosted (the hosted chat page), api, email, slack or voice_web (a browser voice session). The same words as the dashboard's conversation log and the webhooks.

  • state required string

    ai_active, handoff_requested, human_active or closed.

  • started_at required string

    Started At

  • last_message_at optional string

    Last Message At

  • expires_at required string

    Expires At

  • lead_captured required boolean

    Lead Captured

  • summary optional string

    Summary

  • page_url optional string

    Page Url

  • utm optional object

    The campaign that brought the visitor: any of utm_source, utm_medium, utm_campaign, utm_term and utm_content, as the first page of the visit carried them. Empty when there was none.

  • referrer optional string

    The site that sent the visitor (scheme, host and path, never the query string). Empty when there was none.

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.
curl
curl https://www.bidii.ai/api/v2/conversations/CONVERSATION_ID \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"

GET /conversations/{conversation_id}/messages

List a conversation's messages

The messages in the order they were said, with the outcome and the sources behind each AI answer.

Scope: conversations:read

Parameters

  • conversation_id required in the path · string
  • limit optional in the query · integer

    Rows per page, 1 to 100.

  • cursor optional in the query · string

    The next_cursor of the previous page.

Returns Message

  • id required string

    Id

  • role required string

    user or assistant.

  • content required string

    Content

  • actor_type required string

    visitor, ai or owner (a person on the team replied).

  • outcome optional string

    What the turn came to, on AI answers.

  • refused required boolean

    Refused

  • sources required []

    The knowledge behind an AI answer.

  • blocks optional []

    The widgets an answer carried (a form, open times, options, a status card, products, links), each as the widget draws it; null for a plain message.

  • lang optional string

    Lang

  • feedback optional

    Feedback

  • created_at required string

    Created At

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.
curl
curl https://www.bidii.ai/api/v2/conversations/CONVERSATION_ID/messages \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"