Conversas — API Zyron Connect Suite

Module

Conversations

Read Inbox conversations and the complete message history.

GET/conversations/conversations GET/conversations/:id/messages/conversations/:id/messages GET/conversations/resolve/conversations/resolve GET/conversations/:id/conversations/:id PATCH/conversations/:id/conversations/:id

GET/conversationsScope: readOfficial + Basic

List Inbox conversations.

Returns last message, status, connection and basic contact data.

Path parameters

No additional parameters.

Query parameters

Field	Type	Description
`connection_id`optional	uuid	Filters by WhatsApp connection.
`contact_id`optional	uuid	Filters by one contact's conversations.
`phone`optional	string	Filters by the contact's phone (with country code).
`status`optional	open \| closed \| pending	Filters by conversation status.
`limit`optional	number	Records per page. Default 50; maximum 200 on most list endpoints.
`offset`optional	number	Initial page index. Use pagination.next_offset to fetch the next page.

Body fields

This endpoint does not receive a JSON body.

Ready examples

curl -X GET "https://connect.zyronstack.com/api/v1/conversations?status=open&limit=20&offset=0" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Responses

200	Conversations returned.

Response example

{
  "data": [
    {
      "id": "<CONVERSATION_ID>",
      "connection_id": "<CONNECTION_ID>",
      "contact_id": "<CONTACT_ID>",
      "status": "open",
      "last_message_text": "Quero saber mais",
      "last_message_at": "2026-06-15T12:30:00.000Z",
      "unread_count": 2,
      "contacts": {
        "name": "Maria Silva",
        "phone": "5511999998888"
      }
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 41,
    "next_offset": 20
  }
}

GET/conversations/:id/messagesScope: readOfficial + Basic

List messages from one conversation.

Default limit is 100 and maximum is 500. Ordered ascending by created_at.

Path parameters

Field	Type	Description
`id`required	uuid	Conversation ID.

Query parameters

Field	Type	Description
`limit`optional	number	Number of messages. Default 100; maximum 500.
`offset`optional	number	Initial page index.

Body fields

This endpoint does not receive a JSON body.

Ready examples

curl -X GET "https://connect.zyronstack.com/api/v1/conversations/<CONVERSATION_ID>/messages?limit=100&offset=0" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Responses

200	Messages returned.
404	Conversation not found.

Response example

{
  "data": [
    {
      "id": "41a9fa77-6b9d-4d94-a48d-74d036c54121",
      "direction": "in",
      "body": "Quero saber mais",
      "created_at": "2026-06-15T12:30:00.000Z"
    },
    {
      "id": "d38adf37-0f2a-477f-8d8a-238caab12411",
      "direction": "out",
      "body": "Claro, vou te explicar.",
      "created_at": "2026-06-15T12:31:00.000Z"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 2,
    "next_offset": null
  }
}

GET/conversations/resolveScope: readOfficial + Basic

Resolve a conversation by phone.

Avoids a pre-known UUID: use connection_id plus phone, BSUID, parent BSUID or username. Zyron webhooks already deliver it.

Path parameters

No additional parameters.

Query parameters

Field	Type	Description
`connection_id`required	uuid	WhatsApp connection.
`phone`optional	string	Phone with country code.
`business_scoped_user_id`optional	string	Meta BSUID identity.
`parent_business_scoped_user_id`optional	string	Meta parent BSUID.
`username`optional	string	External username stored on the contact.

Body fields

This endpoint does not receive a JSON body.

Ready examples

curl -X GET "https://connect.zyronstack.com/api/v1/conversations/resolve?connection_id=<CONNECTION_ID>&phone=5511999998888" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Responses

200	Conversation resolved.
404	Contact or conversation not found.

Response example

{
  "data": {
    "id": "<CONVERSATION_ID>",
    "connection_id": "<CONNECTION_ID>",
    "status": "open",
    "last_inbound_at": "2026-07-13T13:28:28.347Z",
    "contact": { "id": "<CONTACT_ID>", "phone": "5511999998888" }
  }
}

GET/conversations/:idScope: readOfficial + Basic

Conversation operational detail.

Returns status, tags, assignee, internal note, last_inbound_at (24-hour window) and the contact's identities.

Path parameters

Field	Type	Description
`id`required	uuid	Conversation ID.

Query parameters

No additional parameters.

Body fields

This endpoint does not receive a JSON body.

Ready examples

curl -X GET "https://connect.zyronstack.com/api/v1/conversations/<CONVERSATION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Responses

200	Conversation returned.
404	Conversation not found.

PATCH/conversations/:idScope: writeOfficial + Basic

Update conversation operations.

Close, reopen, set pending, assign and update tags/internal notes.

Path parameters

Field	Type	Description
`id`required	uuid	Conversation ID.

Query parameters

No additional parameters.

Body fields

Field	Type	Description
`status`optional	open \| closed \| pending	Conversation status.
`tags`optional	string[]	Operational tags (up to 30).
`assignee_name`optional	string	Assigned operator.
`internal_note`optional	string	Internal team note, up to 4000 characters.

Ready examples

curl -X PATCH "https://connect.zyronstack.com/api/v1/conversations/<CONVERSATION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "status": "pending",
  "tags": ["lead-quente", "n8n"],
  "assignee_name": "Time comercial"
}'

Responses

200	Conversation updated.