Skip to main content
GET
List Conversations
This is the inbox behind the Tuco unibox. One call gives you the conversation list with each thread’s messages, so you can build your own inbox UI.

Endpoint

  • Method: GET
  • Path: /api/unibox/conversations
  • Auth: Authorization: Bearer tuco_xxxxxxxxxxxxx (workspace key)

Two things that surprise people

A conversation is keyed by recipient, not by lead. There is no leadId on a conversation — it is identified by the phone number or email address at recipient. That is also why the deep link is ?conversation=<address>. The thread holds what actually went out or came in. Messages still queued, pending or scheduled are deliberately not in it — a conversation shows history, not intent. Read the outbound queue from /api/unibox/scheduled instead. If you expect “everything for this contact” here, you will wrongly conclude the follow-ups were lost.

Pagination

Filters

All are query params and all intersect.

Response

Group chats

A group chat your line is in is its own conversation:
  • id starts with group: (for example group:iMessage;+;chat606535035660201399)
  • isGroup is true
  • groupMembers lists each member’s address and name
  • each received message has groupSenderAddress (the member who sent it)
  • there is no lead
To read one group, URL-encode its id in ?conversation=. An unencoded + turns into a space and the group is silently not found.
If the group is not on the page you asked for, it comes back as preselectedConversation. Reply with Send to a Group Chat, or start a new group with Create a Group Chat.

Group chats in your CRM

If your workspace has a CRM connected (GoHighLevel, HubSpot, Pipedrive or Close), every group message is logged on each member’s contact, the same way a 1:1 iMessage is logged there. Example group “Q4 Deal Room” with your line, Raj and Mike:
  • A group with no name is labelled with its members’ numbers instead.
  • Only the person who wrote a message counts as having replied. The other members’ copies don’t trigger reply workflows or change their “replied” status.
  • A member who isn’t in your CRM yet gets a new contact, and a lead in Tuco.
  • Each member’s contact gets each message once. If two members are the same CRM contact, that contact gets it once.
  • Your own Tuco lines are never added as contacts.
  • Turning off CRM activity logging for the workspace turns this off too.

The pending queue

Anything not yet sent:
To stop it going out, see Cancel Pending Messages.
  • GET /api/unibox/tags — the tags you can filter on
  • GET /api/unibox/custom-properties — the property keys for propertyKey
  • GET /api/replies — a flat, paginated feed of inbound replies
  • POST /api/unibox/mark-read, /archive, /flag, /send-reply — act on a conversation
GET /api/unibox/stream (server-sent events) is browser-only and rejects API keys. For server-side updates use webhooks — message.reply fires on every inbound message.

Error responses