مرجع API پیکسول‌چت

Attachment

One file of a message. contentType is sniffed from the stored bytes, never the uploader's claim; kind follows from it. Download through the surface's attachments route — never by id alone.

• idstringrequired
• namestringrequired

  The uploader's file name (display and download name).

• contentTypestringrequired
• kind"image" | "audio" | "video" | "file"required
• sizeBytesintegerrequired
• widthinteger | nullrequired

  An image's width when it could be read.

• heightinteger | nullrequired
• durationMsinteger | nullrequired

  Client-measured recording length; null when absent.

BatchRequest

• contactsContactInput & object[]required

  Each row is a ContactInput plus its `externalId`. Each is judged on its own.

BatchResponse

• resultsobject[]required

  One result per row sent, in the order sent. A bad row does not fail the others.

  فیلدها

  • externalIdstringrequired

    Empty when the row carried no readable one.

  • okbooleanrequired
  • errorobject
    فیلدها

    • codestringrequired
    • messagestringrequired

CallStatus

"queued" | "ringing" | "connecting" | "answered" | "completed" | "no_answer" | "busy" | "failed" | "canceled" | "missed"Outbound: queued → ringing → answered → completed; a call never answered ends no_answer (no pickup), busy (rejected), failed (trunk or LiveKit), or canceled (the staff member hung up first). Inbound (0.45.0): ringing (the caller holds, the desk rings) → connecting (a staff member answered; the voice gateway puts the caller through) → answered → completed; one nobody talked to ends missed, one that could not be put through failed. Only ever moves forward.

Contact

One customer of a business, as the business's server pushed it. Every field is a string; "" when there is none.

• idstringrequired
• externalIdstringrequired

  The business's own id for the customer; unique per business.

• namestringrequired
• phonestringrequired

  09… (11 digits), or empty.

• emailstringrequired

  Lowercase, or empty.

• urlstringrequired

  This customer in the business's own admin (absolute https), or empty.

• flagsContactFlag[]

  Labels the business pushed. Omitted when none. A flag has no reason.

• attributesobject

  Short facts the business pushed. Omitted when none.

• createdAtstring (date-time)required
• updatedAtstring (date-time)required

  When the business last pushed the customer.

ContactFlag

• keystringrequired

  A short key such as aml. Not a sentence.

• labelstringrequired

  What staff read. Not a case narrative.

• tone"info" | "warning" | "danger"required

ContactInput

One customer. A PUT is a full replace of the customer's own fields (missing or null = empty). Lengths are counted in code points after trimming; a `null` reads as not sent.

• namestring | null
• phonestring | null

  An Iranian mobile in any usual spelling; stored as 09…. One that is sent but is not a mobile number is VALIDATION.

• emailstring | null

  Lowercased on the way in.

• urlstring | null

  Absolute https URL.

• telegramIdstring | null

  The customer's Telegram user id as the business knows it (its own Telegram login). A Telegram chat with one of the business's bots is linked to the ONE contact with it, whichever came first (#158). Never shown back.

• flagsarray | null

  Full replace. Each flag is a key, a short label, and a tone. A reason is VALIDATION.

• attributesobject | null

  Full replace. At most 30 facts; each value is at most 200 characters.

• ordersarray | null

  Upserts these orders; never deletes the ones it leaves out.

ContactResponse

• contactContactrequired

ConversationAssistant

• state"active" | "paused" | "handoff"required

  active — it answers; paused — staff stopped it; handoff — it handed the conversation to staff.

• repliesintegerrequired

  Replies it wrote in this conversation.

• handoffReason"" | "customer_asked" | "no_knowledge" | "sensitive" | "unsure" | "limit" | "budget" | "hours" | "error"required

  Why it handed off ("" otherwise). budget also covers a plan that no longer allows the assistant (grace, suspended).

CustomerStreamConversation

A business server's conversation.updated; number is what the tickets API's routes take.

• idstringrequired
• numberintegerrequired
• status"open" | "pending" | "resolved" | "closed"required

CustomerStreamMessage

A business server's message.created or message.updated (0.32.0 — read the whole thread again; never a note). `message` is present on every message.created (TicketsMessage) and absent on message.updated.

• conversationIdstringrequired
• numberintegerrequired
• messageIdstringrequired
• author"customer" | "agent" | "assistant" | "system"required
• messageTicketsMessage

  The tickets-API public message. Present on every message.created and absent on message.updated. Never a note.

Deleted

• deletedbooleanrequired

  false when there was nothing to delete (a delete is idempotent).

ErrorEnvelope

• okfalserequired
• errorobjectrequired
  فیلدها

  • codestringrequired

    Machine-readable, e.g. VALIDATION.

  • messagestringrequired

    English, for the developer; may change.

ImportAliasList

• itemsobject[]required
  فیلدها

  • aliasstringrequired
  • conversationIdstringrequired
  • numberintegerrequired
  • kind"ticket" | "live"required
  • status"open" | "pending" | "resolved" | "closed"required
  • channelstringrequired
  • contactExternalIdstring | nullrequired
  • messageCountintegerrequired

    Every message, internal notes and deleted ones included.

ImportConversation

• sourceIdstringrequired

  The old system's id; the import's idempotency key and an alias.

• aliasesstring[]

  Other old names («PX-123»).

• kind"ticket" | "live"required
• channel"widget" | "api" | "email" | "telegram" | "bale" | "phone" | "manual"required
• status"open" | "pending" | "resolved" | "closed"required
• subjectstring
• createdAtstring (date-time)required
• resolvedAtstring (date-time)

  Defaults to the last activity for a resolved or closed one.

• orderExternalIdstring
• assigneePhonestring

  A staff member's mobile; anyone not on the team is left unassigned.

• contactobject

  The customer by the business's own id — made from the stub when missing, never changed. A ticket with one is shown to that customer through the tickets API; a live chat never is.

  فیلدها

  • externalIdstringrequired
  • namestring
  • phonestring
  • emailstring
• customerobject

  A guest's own details (no contact).

  فیلدها

  • namestring
  • phonestring
  • emailstring
• channelIdentityobject

  Live only: the chat the conversation continues on — the customer's next message there joins it while it is not closed.

  فیلدها

  • channel"telegram" | "bale"required
  • externalChatIdstringrequired
  • externalUserIdstring

    Defaults to externalChatId (a one-to-one chat).

  • usernamestring
  • connectionIdstring

    One of the business's connections on that channel; none = its own channel (the API key).

• messagesobject[]required
  فیلدها

  • sourceIdstringrequired
  • author"customer" | "agent" | "system"required
  • staffPhonestring

    An agent's mobile; anyone not on the team is written with no author id («کارمند قبلی»).

  • bodystring

    Required unless the message carries attachments.

  • internalboolean

    A staff-only note (agent only).

  • createdAtstring (date-time)required
  • editedAtstring (date-time)
  • deletedAtstring (date-time)
  • attachmentsstring[]

    Upload ids (POST /api/v1/uploads).

  • revisionsobject[]
    فیلدها

    • bodystringrequired
    • staffPhonestring
    • createdAtstring (date-time)required
• ratingobject
  فیلدها

  • scoreintegerrequired
  • commentstring
  • createdAtstring (date-time)required

ImportRequest

• dryRunboolean

  Judge and plan only; nothing is written.

• conversationsImportConversation[]required

ImportResponse

• dryRunbooleanrequired
• staffPhonesobjectrequired

  The request's distinct staff phones: on the team (written as that person) or not («کارمند قبلی»). On a dry run too.

  فیلدها

  • knownintegerrequired
  • unknownintegerrequired
• resultsobject[]required

  One per row, in the order sent.

  فیلدها

  • sourceIdstringrequired
  • status"created" | "appended" | "unchanged" | "skipped" | "refused"required

    On a dry run, what would happen. skipped: imported before, erased or merged away since.

  • conversationIdstring | nullrequired
  • numberinteger | nullrequired
  • newMessagesstring[]required

    The source ids of the messages written (would be).

  • errorobject | nullrequired
    فیلدها

    • codestringrequired
    • messagestringrequired

IngestMe

• workspaceobjectrequired
  فیلدها

  • idstringrequired
  • namestringrequired
  • siteUrlstringrequired
  • accountIdstringrequired

    The business's billing account (#190): the company's id, else the owner's user id. With id it addresses the dashboard: /dashboard/{accountId}/business/{id}/….

• contactsintegerrequired

MessageBlock

یکی از این شکل‌ها: object · object · object · object · object

MessageButton

یکی از این شکل‌ها: object · object

MessageReplyTo

• idstringrequired
• author"customer" | "agent" | "assistant" | "system"required
• excerptstringrequired
• deletedbooleanrequired

Order

One order of a contact as the business describes it — a summary, no line items. A contact keeps its 20 newest by placedAt.

• idstringrequired
• externalIdstringrequired
• numberstringrequired

  What the business calls it on screen; defaults to externalId.

• titlestringrequired
• statusstringrequired

  The business's own label, free text.

• amountstringrequired

  A decimal string in `currency`.

• currencystringrequired

  IRT, IRR, USD, USDT, …

• urlstringrequired

  This order in the business's own admin (absolute https), or empty.

• placedAtstring (date-time)required
• createdAtstring (date-time)required
• updatedAtstring (date-time)required

OrderConversation

One conversation about an order, for the business's admin.

• idstringrequired
• numberintegerrequired
• kind"live" | "ticket"required
• status"open" | "pending" | "resolved" | "closed"required
• subjectstringrequired
• orderExternalIdstringrequired
• contactIdstring | nullrequired
• contactExternalIdstring | nullrequired

  The business's own id for the customer (#190), for reading the thread through the customer's routes; null with no contact or one staff made at the desk.

• assistantConversationAssistant | nullrequired

  The AI assistant on it (#190); null when it never answered.

• lastActivityAtstring (date-time)required
• createdAtstring (date-time)required

OrderConversationList

• itemsOrderConversation[]required

OrderInput

• numberstring | null

  Defaults to the order's externalId (required when that is longer than 60).

• titlestring | null
• statusstring | null
• amountstringrequired

  A decimal string (the service also reads a bare JSON number by its digits; the public door and SDK take a string).

• currencystringrequired
• urlstring | null

  Absolute https URL.

• placedAtstring (date-time)required

  ISO 8601 with a time zone.

OrderResponse

• orderOrderrequired

Role

"OWNER" | "ADMIN" | "MEMBER"The VIEWER's role — OWNER on their own workspace, OWNER / ADMIN as a company's representative, ADMIN / MEMBER as a member of the business's team.

Staff

• userIdstring (uuid)required
• roleRolerequired

StreamAborted

message.aborted, the same JSON on every audience that may see it. A signal: no id, never replayed, never stored. That reply will not be stored. The stored reply, when one is written, is an ordinary message.created. A note's abort never leaves the staff stream.

• conversationIdstringrequired
• messageIdstringrequired

StreamDelta

message.delta, the same JSON on every audience that may see it. A signal: no id, never replayed, never stored, never sent to a channel or webhook. seq is 1, 2, 3… for this messageId and is contiguous. chunk is decoded reply text, never the model's JSON. A visitor hears it only on that conversation's own stream. A note's delta never leaves the staff stream.

• conversationIdstringrequired
• messageIdstringrequired
• seqintegerrequired
• chunkstringrequired

TicketsCategory

• idstringrequired
• namestringrequired
• descriptionstringrequired

TicketsCategoryList

• categoriesTicketsCategory[]required

  The live ones, in the dashboard's order.

TicketsConversation

A conversation as the customer's support UI shows it. Never a staff id, an internal note, the assignee, the priority, or the customer's phone and email.

• idstringrequired
• numberintegerrequired
• kind"live" | "ticket"required
• status"open" | "pending" | "resolved" | "closed"required
• channel"widget" | "phone" | "email" | "manual" | "api"required
• openedByStaffbooleanrequired

  Staff opened it at the desk (channel phone, email or manual).

• subjectstringrequired
• categoryobject | nullrequired
  فیلدها

  • idstringrequired
  • namestringrequired
• orderExternalIdstring | nullrequired

  The business's order it is about, as sent.

• lastMessagestringrequired
• lastAuthor"customer" | "agent" | "assistant" | "system"required
• messageCountintegerrequired

  Public messages.

• unreadCountintegerrequired

  Staff / assistant messages after the customer's last read through this API.

• awaitingCustomerbooleanrequired

  status pending: staff answered.

• canRatebooleanrequired

  Resolved or closed, and that resolution not rated yet.

• ratingTicketsRating | nullrequired
• assistantConversationAssistant | nullrequired

  The AI assistant on it (#190), for the business's own staff — its state, replies and why it handed off; null when it never answered.

• lastActivityAtstring (date-time)required
• resolvedAtstring | null (date-time)required
• createdAtstring (date-time)required

TicketsConversationPage

• itemsTicketsConversation[]required
• nextCursorstring | nullrequired

  Opaque; null on the last page.

TicketsConversationResult

• conversationTicketsConversationrequired

TicketsCreateRequest

• kind"ticket" | "live"required
• subjectstring

  Required for a ticket.

• bodystring
• categoryIdstring | null
• orderExternalIdstring | null
• attachmentsstring[]

  Upload ids from POST /api/v1/uploads, not sent yet; with any, body may be empty.

• contactobject

  Used only when the business has no contact with this externalId: the contact is made from it (counted against the contact ceiling). Judged like a push on every request — a malformed one is VALIDATION even for an existing contact, which is never changed by it.

  فیلدها

  • namestring | null
  • phonestring | null
  • emailstring | null

TicketsMessage

A public message; one staff deleted is never listed (0.32.0).

• replyToMessageReplyTo | nullrequired
• idstringrequired
• author"customer" | "agent" | "assistant" | "system"required
• senderWidgetTeamMember | null

  Public first name and opaque avatar URL only; omitted without consent or for non-agent messages.

• bodystringrequired
• blocksMessageBlock[]required

  Rich staff/assistant content; [] for customer messages or none.

• attachmentsAttachment[]required
• createdAtstring (date-time)required
• editedAtstring | null (date-time)required

  When staff last edited it (0.32.0); null when never.

TicketsRating

• idstringrequired
• scoreintegerrequired
• commentstringrequired
• createdAtstring (date-time)required

TicketsRatingRequest

• scoreintegerrequired
• commentstring | null

TicketsRatingResult

• ratingTicketsRatingrequired
• conversationTicketsConversationrequired

TicketsReplyRequest

• bodystring

  Required unless attachments are sent.

• attachmentsstring[]

  Upload ids from POST /api/v1/uploads, not sent yet.

TicketsReplyResult

• conversationTicketsConversationrequired
• messageTicketsMessagerequired
• messagesTicketsMessage[]required

TicketsStatusRequest

• status"resolved" | "open"required

TicketsThread

• conversationTicketsConversationrequired
• messagesTicketsMessage[]required

  Public messages, oldest first.

Upload

PUT the file's bytes to uploadUrl (any Content-Type; at most maxBytes) before expiresAt (5 minutes), then name uploadId in a message's attachments within a day. Media answers 413 over the cap and 415 for a type it does not take.

• uploadIdstringrequired
• uploadUrlstringrequired
• expiresAtstring (date-time)required
• maxBytesintegerrequired
• visitorTokenstring

  Widget only: present when this call minted the visitor's token.

UploadRequest

The file about to be PUT. contentType and sizeBytes only pick the cap (a video's or a file's) and refuse an obviously too large file early; the stored bytes decide the type and size.

• namestring

  Kept (cleaned, at most 200 characters) as the file's display and download name.

• contentTypestring
• sizeBytesinteger
• durationMsinteger

  Optional client-measured recording length in milliseconds.

WebhookChange

• field"status" | "kind" | "assignee"required

  kind: a live chat staff turned into a ticket (0.33.0) — from live, to ticket.

• fromstring | nullrequired
• tostring | nullrequired

WebhookConversation

The conversation after the change. Never the customer's name, phone, email, page or visitor token.

• idstringrequired
• numberintegerrequired
• kind"live" | "ticket"required
• channelstringrequired
• status"open" | "pending" | "resolved" | "closed"required
• priority"low" | "normal" | "high" | "urgent"required
• subjectstringrequired
• categoryIdstring | nullrequired
• assigneeUserIdstring | nullrequired
• contactobject | nullrequired

  The business's customer the conversation is linked to — our id, theirs, and whether the link is proven.

  فیلدها

  • idstringrequired
  • externalIdstringrequired
  • verifiedbooleanrequired

    true only when the conversation was started by a visitor the business's page signed in as this customer (a signed widget identity), or by the business's own server through the tickets API, and is still linked to them; then every customer-authored event in it (created, customer_replied) was written by that customer. false for every other link — a phone or email someone typed into the widget, a channel, or staff (a staff-linked ticket is shown to its customer by the tickets API, but is not verified) — which proves nothing about who is writing: a receiver must never treat it as the customer's identity.

• createdAtstring (date-time)required
• updatedAtstring (date-time)required
• lastActivityAtstring (date-time)required
• mergedIntoobject

  The conversation staff merged this one into (0.33.0, #171) — its messages are there now. The last key, absent when never merged.

  فیلدها

  • idstringrequired
  • numberintegerrequired

WebhookConversationPayload

Every conversation event. `message` is set on created (the first message, when public) and the two *_replied events; `change` on status_changed and assigned; each null otherwise. conversation.rated has both null and adds `rating` — the last key, absent from every other event.

• event"conversation.created" | "conversation.customer_replied" | "conversation.staff_replied" | "conversation.status_changed" | "conversation.assigned" | "conversation.rated" | "conversation.message_edited" | "conversation.message_deleted" | "conversation.merged"required
• occurredAtstring (date-time)required

  UTC, milliseconds.

• workspaceIdstringrequired
• conversationWebhookConversationrequired
• messageWebhookMessage | nullrequired
• changeWebhookChange | nullrequired
• ratingWebhookRating

  conversation.rated only.

WebhookMessage

A public message (never an internal note).

• idstringrequired
• author"customer" | "agent" | "assistant"required
• authorUserIdstring | nullrequired
• bodystringrequired
• blocksMessageBlock[]required

  Rich staff/assistant content; [] for customer messages or none.

• attachmentsAttachment[]required

  Its files; download one through the tickets API (GET …/conversations/{number}/attachments/{id}).

• createdAtstring (date-time)required
• editedAtstring (date-time)

  message_edited only (absent otherwise): when staff edited it; body is the new text.

• deletedAtstring (date-time)

  message_deleted only (absent otherwise): when staff deleted it; body is empty and blocks and attachments [] — the customer no longer sees it.

WebhookPayload

یکی از این شکل‌ها: WebhookConversationPayload · WebhookTestPayload

WebhookRating

The rating a conversation.rated is about.

• idstringrequired
• scoreintegerrequired
• commentstringrequired

  "" for none.

• source"api" | "widget"required

  api: the tickets API; widget: the widget on the site (0.29.0)

• resolvedAtstring (date-time)required

  The resolution rated.

• createdAtstring (date-time)required

WebhookTestPayload

• event"webhook.test"required
• occurredAtstring (date-time)required
• workspaceIdstringrequired
• webhookIdstringrequired

WidgetTeamMember

• firstNamestringrequired
• avatarUrlstringrequired