Pular para o conteúdo
CognizyCognizyAjuda
Entrar
Nesta área

Conversations

Create and manage conversations, including tags and assignment.

List or search conversations

get/v1/public/conversations

Paginated list of conversations in the organization. Combine query (free-text over contact name/subject) with structured filters (status, channel, assignedToId, tagId, from/to). Returns data + meta.{total,page,limit,totalPages}.

Parâmetros

limitnumberopcional· consulta
Range 1–100
pagenumberopcional· consulta
tostringopcional· consulta
ISO datetime (exclusive)
fromstringopcional· consulta
ISO datetime (inclusive)
tagIdstringopcional· consulta
Repeat to OR multiple tag ids
assignedToIdstringopcional· consulta
channelWEB_CHAT | WHATSAPP | EMAIL | INSTAGRAM | MESSENGER | TELEGRAM | APIopcional· consulta
statusOPEN | PENDING | RESOLVED | CLOSEDopcional· consulta
querystringopcional· consulta

Respostas

  • 200

Exemplos

bash
curl -X GET "https://api.cognizy.ai/api/v1/public/conversations" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

Create conversation

post/v1/public/conversations

Aceita Idempotency-Key

Creates a conversation tied to a contact identified by externalId. The contact is upserted on each call.

Parâmetros

Sem parâmetros.

Corpo (JSON)obrigatório

agentIdstringopcional
Agent identifier. Currently only "default" is supported (the organization's configured agent). Omit to use the default.
contactobjectobrigatório
Contact participating in the conversation. Upserted by externalId.
contact.externalIdstringobrigatório
Stable identifier for the contact in your own system. Cognizy upserts the contact by this value scoped to your organization.
contact.namestringopcional
contact.phonestringopcional
contact.emailstring (email)opcional
contact.metadataobjectopcional
Free-form custom fields stored alongside the contact.
accountobjectopcional
External account this contact belongs to (B2B2C). When provided, conversations are grouped by this account in the inbox.
account.externalIdstringobrigatório
Identifier of the customer/tenant in the host SaaS that the contact belongs to. Cognizy upserts the ExternalAccount by this value (scoped to your organization + source).
account.namestringopcional
Display name of the account (e.g. the customer's company name). Shown as a badge in the inbox. Falls back to externalId if omitted.
account.sourcestringopcional
Identifier of the host SaaS sending this account (e.g. "mylar-pro"). Defaults to "api" when omitted.
account.metadataobjectopcional
Free-form metadata about the account (plan, mrr, website, …).
subjectstringopcional
Optional subject/title for the conversation.
metadataobjectopcional
Free-form metadata attached to the conversation.

Respostas

  • 201

Exemplos

bash
curl -X POST "https://api.cognizy.ai/api/v1/public/conversations" \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "agentId": "default",
  "contact": {
    "externalId": "user-42",
    "name": "Alice Silva",
    "phone": "+5511999999999",
    "email": "alice@example.com",
    "metadata": {
      "plan": "pro",
      "signupSource": "mobile"
    }
  },
  "account": {
    "externalId": "imob-456",
    "name": "Imóveis Acme",
    "source": "mylar-pro",
    "metadata": {
      "plan": "pro",
      "cidade": "São Paulo"
    }
  },
  "subject": "Order #1234 — refund request",
  "metadata": {}
}'

Get conversation

get/v1/public/conversations/{id}

Parâmetros

idstringobrigatório· caminho

Respostas

  • 200

Exemplos

bash
curl -X GET "https://api.cognizy.ai/api/v1/public/conversations/<id>" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

Close conversation

post/v1/public/conversations/{id}/close

Aceita Idempotency-Key

Parâmetros

idstringobrigatório· caminho

Respostas

  • 200

Exemplos

bash
curl -X POST "https://api.cognizy.ai/api/v1/public/conversations/<id>/close" \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Enable or disable AI on a conversation

patch/v1/public/conversations/{id}/ai

Aceita Idempotency-Key

Hands a conversation to or from Cognizy's AI. Set isAiActive: false to take the thread over with your own system — inbound messages keep arriving on your message.received webhook and you reply through the Send API — or true to hand it back. This is the programmatic equivalent of the dashboard's AI toggle. Note it is per conversation and is reset when a conversation is reopened; to silence our AI for an entire number or organization, use the headless aiMode setting instead.

Parâmetros

idstringobrigatório· caminho

Corpo (JSON)obrigatório

isAiActivebooleanobrigatório
Whether Cognizy's AI answers this conversation. Set false to take the thread over with your own system (replies then go out through the Send API); set true to hand it back.

Respostas

  • 200

Exemplos

bash
curl -X PATCH "https://api.cognizy.ai/api/v1/public/conversations/<id>/ai" \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "isAiActive": false
}'

Attach a tag to a conversation

post/v1/public/conversations/{id}/tags

Aceita Idempotency-Key

Idempotent: re-attaching the same (conversation, tag) pair is a no-op. Triggers TAG_ADDED automation rules — agents can use this to flag conversations for downstream workflows.

Parâmetros

idstringobrigatório· caminho
Conversation ID

Corpo (JSON)obrigatório

tagIdstringobrigatório
Tag ID to attach to the conversation

Respostas

  • 204Tag attached (or already attached — idempotent)
  • 400Missing or invalid `tagId`
  • 404Conversation or tag not found

Exemplos

bash
curl -X POST "https://api.cognizy.ai/api/v1/public/conversations/<id>/tags" \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "tagId": "tag_123"
}'

Detach a tag from a conversation

delete/v1/public/conversations/{id}/tags/{tagId}

Parâmetros

idstringobrigatório· caminho
Conversation ID
tagIdstringobrigatório· caminho
Tag ID to detach

Respostas

  • 204Tag detached (or was not attached — idempotent)
  • 404Conversation or tag not found

Exemplos

bash
curl -X DELETE "https://api.cognizy.ai/api/v1/public/conversations/<id>/tags/<tagId>" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

Assign or unassign a conversation

post/v1/public/conversations/{id}/assign

Aceita Idempotency-Key

Set the assigned agent for a conversation. Pass userId: null (or omit) to unassign. The user must be a member of the same org. Triggers SLA timers and assignment notifications same as in-app.

Parâmetros

idstringobrigatório· caminho
Conversation ID

Corpo (JSON)obrigatório

userIdstringopcional
User ID to assign. Pass null or omit to unassign.

Respostas

  • 200Conversation assignment updated
  • 400Invalid `userId`
  • 404Conversation or user not found in organization

Exemplos

bash
curl -X POST "https://api.cognizy.ai/api/v1/public/conversations/<id>/assign" \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "userId": "user_123"
}'

Toda a referência