Tickets

GET /tickets

List tickets

The workspace's tickets, newest first: whose move it is (status), who has it, the conversation it belongs to, the team's own fields in custom, the tags the helpdesk rules wrote (narrow with tag), and how long the first answer and the resolution took.

Scope: tickets:read

Parameters

• 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.

• agent_id optional in the query · string

  Only tickets of this agent.

• status optional in the query · "new" | "on_you" | "on_customer" | "on_hold" | "closed"

  Only tickets in this status.

• assignee_user_id optional in the query · string

  Only tickets held by this member (a user id).

• tag optional in the query · string

  Only tickets carrying this tag (one the workspace's helpdesk rules wrote; see tags on the ticket).

Returns Ticket

• id required string

  Id

• agent_id required string

  Agent Id

• conversation_id optional string

  Conversation Id

• contact_id optional string

  Contact Id

• status required string

  new (nobody has replied), on_you (the customer wrote last), on_customer (the team wrote last), on_hold or closed.

• priority required string

  low, normal or high.

• assignee_user_id optional string

  The member who has it; null for nobody.

• team_id optional string

  Team Id

• subject required string

  Subject

• channel required string

  The conversation's channel when the ticket opened: website, hosted, api, email, slack or voice_web.

• language required string

  The visitor's language: en or ar.

• source required string

  What opened it: handoff, or conversation (the every-conversation option).

• custom optional object

  The workspace's ticket fields, by key.

• tags optional string[]

  The tags the workspace's helpdesk rules set on it.

• handoff_at optional string

  When a person was last asked in.

• first_response_at optional string

  First Response At

• first_response_seconds optional integer

  From the handoff (or the ticket's start) to the first reply by a person.

• last_customer_message_at optional string

  Last Customer Message At

• last_agent_message_at optional string

  Last Agent Message At

• closed_at optional string

  Closed At

• closed_by optional string

  The member who closed it; null when a key did.

• resolution_seconds optional integer

  From the ticket's start to its close.

• csat_score optional integer

  The visitor's rating after the ticket closed: 1 good, -1 bad.

• csat_comment optional string

  What the visitor added to the rating, if anything.

• csat_at optional string

  When the visitor rated.

• created_at required string

  Created At

• updated_at required string

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

GET /tickets/{ticket_id}

Get a ticket

One ticket by id.

Scope: tickets:read

Parameters

• ticket_id required in the path · string

Returns Ticket

• id required string

  Id

• agent_id required string

  Agent Id

• conversation_id optional string

  Conversation Id

• contact_id optional string

  Contact Id

• status required string

  new (nobody has replied), on_you (the customer wrote last), on_customer (the team wrote last), on_hold or closed.

• priority required string

  low, normal or high.

• assignee_user_id optional string

  The member who has it; null for nobody.

• team_id optional string

  Team Id

• subject required string

  Subject

• channel required string

  The conversation's channel when the ticket opened: website, hosted, api, email, slack or voice_web.

• language required string

  The visitor's language: en or ar.

• source required string

  What opened it: handoff, or conversation (the every-conversation option).

• custom optional object

  The workspace's ticket fields, by key.

• tags optional string[]

  The tags the workspace's helpdesk rules set on it.

• handoff_at optional string

  When a person was last asked in.

• first_response_at optional string

  First Response At

• first_response_seconds optional integer

  From the handoff (or the ticket's start) to the first reply by a person.

• last_customer_message_at optional string

  Last Customer Message At

• last_agent_message_at optional string

  Last Agent Message At

• closed_at optional string

  Closed At

• closed_by optional string

  The member who closed it; null when a key did.

• resolution_seconds optional integer

  From the ticket's start to its close.

• csat_score optional integer

  The visitor's rating after the ticket closed: 1 good, -1 bad.

• csat_comment optional string

  What the visitor added to the rating, if anything.

• csat_at optional string

  When the visitor rated.

• created_at required string

  Created At

• updated_at required string

  Updated 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 https://www.bidii.ai/api/v2/tickets/TICKET_ID \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"

PATCH /tickets/{ticket_id}

Update a ticket

Change any of: status (on_hold, closed, or open to release a hold or reopen), priority, assignee_user_id (null for nobody) and custom (merged by key and checked against the workspace's ticket fields). Send at least one. Every change emits ticket.updated; closing emits ticket.closed as well and hands the visitor back to the assistant.

Scope: tickets:write

Parameters

• ticket_id required in the path · string

Request body

• status optional "open" | "on_hold" | "closed"

  on_hold holds it, closed closes it, open releases a hold or reopens.

• priority optional "low" | "normal" | "high"

  Priority

• assignee_user_id optional string

  A member who can answer on the ticket's agent; null gives it to nobody.

• custom optional object

  Merged into the ticket's fields by key; a null removes a key.

Returns Ticket

• id required string

  Id

• agent_id required string

  Agent Id

• conversation_id optional string

  Conversation Id

• contact_id optional string

  Contact Id

• status required string

  new (nobody has replied), on_you (the customer wrote last), on_customer (the team wrote last), on_hold or closed.

• priority required string

  low, normal or high.

• assignee_user_id optional string

  The member who has it; null for nobody.

• team_id optional string

  Team Id

• subject required string

  Subject

• channel required string

  The conversation's channel when the ticket opened: website, hosted, api, email, slack or voice_web.

• language required string

  The visitor's language: en or ar.

• source required string

  What opened it: handoff, or conversation (the every-conversation option).

• custom optional object

  The workspace's ticket fields, by key.

• tags optional string[]

  The tags the workspace's helpdesk rules set on it.

• handoff_at optional string

  When a person was last asked in.

• first_response_at optional string

  First Response At

• first_response_seconds optional integer

  From the handoff (or the ticket's start) to the first reply by a person.

• last_customer_message_at optional string

  Last Customer Message At

• last_agent_message_at optional string

  Last Agent Message At

• closed_at optional string

  Closed At

• closed_by optional string

  The member who closed it; null when a key did.

• resolution_seconds optional integer

  From the ticket's start to its close.

• csat_score optional integer

  The visitor's rating after the ticket closed: 1 good, -1 bad.

• csat_comment optional string

  What the visitor added to the rating, if anything.

• csat_at optional string

  When the visitor rated.

• created_at required string

  Created At

• updated_at required string

  Updated 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.
• 409 conflict: the ticket cannot move to that status from where it is.

curl -X PATCH https://www.bidii.ai/api/v2/tickets/TICKET_ID \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"priority": "high"}'