In this area

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}.

Parameters

limitnumberoptional· query: Range 1–100
pagenumberoptional· query
tostringoptional· query: ISO datetime (exclusive)
fromstringoptional· query: ISO datetime (inclusive)
tagIdstringoptional· query: Repeat to OR multiple tag ids
assignedToIdstringoptional· query
channelWEB_CHAT | WHATSAPP | EMAIL | INSTAGRAM | MESSENGER | TELEGRAM | APIoptional· query
statusOPEN | PENDING | RESOLVED | CLOSEDoptional· query
querystringoptional· query

Field	In	Type	Description
`limit`optional	query	number	Range 1–100
`page`optional	query	number
`to`optional	query	string	ISO datetime (exclusive)
`from`optional	query	string	ISO datetime (inclusive)
`tagId`optional	query	string	Repeat to OR multiple tag ids
`assignedToId`optional	query	string
`channel`optional	query	WEB_CHAT \| WHATSAPP \| EMAIL \| INSTAGRAM \| MESSENGER \| TELEGRAM \| API
`status`optional	query	OPEN \| PENDING \| RESOLVED \| CLOSED
`query`optional	query	string

Responses

200

Examples

bash

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

Create conversation

post/v1/public/conversations

Accepts Idempotency-Key

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

Parameters

No parameters.

Body (JSON)required

agentIdstringoptional: Agent identifier. Currently only "default" is supported (the organization's configured agent). Omit to use the default.
contactobjectrequired: Contact participating in the conversation. Upserted by externalId.
contact.externalIdstringrequired: Stable identifier for the contact in your own system. Cognizy upserts the contact by this value scoped to your organization.
contact.namestringoptional
contact.phonestringoptional
contact.emailstring (email)optional
contact.metadataobjectoptional: Free-form custom fields stored alongside the contact.
accountobjectoptional: External account this contact belongs to (B2B2C). When provided, conversations are grouped by this account in the inbox.
account.externalIdstringrequired: 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.namestringoptional: 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.sourcestringoptional: Identifier of the host SaaS sending this account (e.g. "mylar-pro"). Defaults to "api" when omitted.
account.metadataobjectoptional: Free-form metadata about the account (plan, mrr, website, …).
subjectstringoptional: Optional subject/title for the conversation.
metadataobjectoptional: Free-form metadata attached to the conversation.

Field	Type	Description
`agentId`optional	string	Agent identifier. Currently only `"default"` is supported (the organization's configured agent). Omit to use the default.
`contact`required	object	Contact participating in the conversation. Upserted by `externalId`.
`contact.externalId`required	string	Stable identifier for the contact in your own system. Cognizy upserts the contact by this value scoped to your organization.
`contact.name`optional	string
`contact.phone`optional	string
`contact.email`optional	string (email)
`contact.metadata`optional	object	Free-form custom fields stored alongside the contact.
`account`optional	object	External account this contact belongs to (B2B2C). When provided, conversations are grouped by this account in the inbox.
`account.externalId`required	string	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.name`optional	string	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.source`optional	string	Identifier of the host SaaS sending this account (e.g. "mylar-pro"). Defaults to "api" when omitted.
`account.metadata`optional	object	Free-form metadata about the account (plan, mrr, website, …).
`subject`optional	string	Optional subject/title for the conversation.
`metadata`optional	object	Free-form metadata attached to the conversation.

Responses

201

Examples

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}

Parameters

idstringrequired· path

Field	In	Type	Description
`id`required	path	string

Responses

200

Examples

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

Accepts Idempotency-Key

Parameters

idstringrequired· path

Field	In	Type	Description
`id`required	path	string

Responses

200

Examples

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

Accepts 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.

Parameters

idstringrequired· path

Field	In	Type	Description
`id`required	path	string

Body (JSON)required

isAiActivebooleanrequired: 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.

Field	Type	Description
`isAiActive`required	boolean	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.

Responses

200

Examples

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

Accepts 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.

Parameters

idstringrequired· path: Conversation ID

Field	In	Type	Description
`id`required	path	string	Conversation ID

Body (JSON)required

tagIdstringrequired: Tag ID to attach to the conversation

Field	Type	Description
`tagId`required	string	Tag ID to attach to the conversation

Responses

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

Examples

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}

Parameters

idstringrequired· path: Conversation ID
tagIdstringrequired· path: Tag ID to detach

Field	In	Type	Description
`id`required	path	string	Conversation ID
`tagId`required	path	string	Tag ID to detach

Responses

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

Examples

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

Accepts 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.

Parameters

idstringrequired· path: Conversation ID

Field	In	Type	Description
`id`required	path	string	Conversation ID

Body (JSON)required

userIdstringoptional: User ID to assign. Pass null or omit to unassign.

Field	Type	Description
`userId`optional	string	User ID to assign. Pass null or omit to unassign.

Responses

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

Examples

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"
}'

Full reference