Inbox Ticketing API

A public REST API for managing Inbox tickets programmatically — create and update tickets, post public replies and internal notes, assign to agents or groups, manage tags and attachments, list custom views, and search tickets.

Early access

This API is in early access. Reach out to our team to get access.

Base URL

All endpoints are served under:

https://<host>/api/agents/public/v1

<host> is your region's platform host (for example cloud.yellow.ai).

Authentication

Every request must send an API key and target a bot:

• Header — x-api-key: <key>
• Query — ?bot=<botId> (required on every endpoint)

The key is resolved to a user, who must hold an agent/admin role on the target bot. Requests with a missing/invalid key — or for a bot the key has no access to — are rejected with 401. These endpoints accept API-key auth only (dashboard session cookies are not accepted).

All failures return a JSON error body of the form:

{ "error": "human-readable message" }

Response & status codes

Code	Meaning
200	Success — also returned by create when an active ticket already exists
201	Ticket created
400	Invalid request (validation failed — see the message)
401	Missing/invalid API key, no role on the bot, or the feature is not enabled
404	Ticket (or referenced agent) not found
422	Unsupported ticket status transition
500	Internal error

Conventions

Requester identity

A ticket is created for a requester identified by one of email, phone, or external_id (the first present becomes the contact's uid). email and phone are format-validated.

Source

source is required on create — it identifies the origin channel. Allowed values:

whatsapp, facebook, yellowmessenger, appleBusinessChat, email, lazada, instagram.

Priority

low, normal, high, and urgent are accepted and mapped to LOW / MEDIUM / HIGH (normal → MEDIUM, urgent → HIGH). Defaults to MEDIUM.

Ticket status transitions

On PUT /tickets/{id}, the status field accepts:

• solved or closed → resolves the ticket.
• open → reopens it. Reopening creates a new ticket linked to the original and returns both: { "ticket": <new>, "previousTicketId": <old id> }.
• Any other value → 422.

Custom fields

customFields must be a key-value object (for example { "plan": "enterprise" }). Keys must be configured in the bot's support settings; unknown keys are rejected with 400.

Pagination

List, search, and message endpoints return up to 100 items per page. Pass ?page=<n> (0-based). Responses include total, count, and next_page / previous_page (either may be null).

Search query

GET /ticket/search accepts a compact query string:

• type:ticket — no-op (only tickets are returned).
• status:<value> — exact status match.
• status<<value> — every status ordered before <value> in the ticket lifecycle: INITIAL → QUEUED → OPEN → ASSIGNED → WRAP-UP → RESOLVED → MISSED.

Example: type:ticket status<solved returns all not-yet-resolved tickets.

Quickstart — create a ticket

curl -X POST 'https://<host>/api/agents/public/v1/tickets?bot=<botId>' \
  -H 'x-api-key: <key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "requester": { "email": "[email protected]", "name": "Jane Doe" },
    "source": "yellowmessenger",
    "subject": "Unable to log in",
    "priority": "normal",
    "tags": ["login"]
  }'

A new ticket returns 201; if the requester already has an active ticket, that one is returned with 200 (no duplicate is created).

Endpoints

Method	Purpose	Reference
POST	Create (or find an existing) ticket	Create a ticket
PUT	Update a ticket — status, comment, assignment, tags, custom fields	Update a ticket
GET	List a ticket's messages (paginated)	List ticket messages
POST	Upload and attach a file	Upload an attachment
PUT	Replace a ticket's tags	Replace ticket tags
DELETE	Remove tags from a ticket	Remove ticket tags
GET	List custom views	List custom views
GET	List tickets in a view (paginated)	List tickets in a view
GET	Search tickets	Search tickets

Endpoint notes

• Create a ticket — create-or-find; requires source; validates email/phone/priority and rejects unknown custom-field keys.
• Update a ticket — send one intent per request: status, comment ({ "body", "public" } — public: false posts an internal note), category/group_id, assignedTo/assignee_id, customFields, or tags.
• List ticket messages — paginated (?page=<n>, see Pagination above, newest page first). ?sort_order=asc (oldest first within a page, default) or desc. Internal notes are returned with public: false.
• Upload an attachment — multipart/form-data with a single field named file (max 25 MB).
• Tags — PUT replaces the full tag set; DELETE removes the listed tags. The body is { "tags": [ ... ] } (must be an array).