Conversations

Conversations and messages

GET`/api/conversation-stages`

The team's sales stages

Required scope: conversations.read

bash

curl "https://api.zapyflow.com.br/api/conversation-stages" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK

POST`/api/conversation-stages`

Create a sales stage

Required scope: conversation_stages.write

Request body

Field	Type	Required	Constraints
`name`	`string`	yes	min 1, max 40
`color`	`string`	yes	—

bash

curl -X POST "https://api.zapyflow.com.br/api/conversation-stages" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Responses

201 — Created
409 — Conflict with the current state
422 — Understood, but rejected by a rule

PATCH`/api/conversation-stages/{id}`

Rename or recolour a sales stage

Required scope: conversation_stages.write

Parameter	In	Required
`id`	path	yes

Request body

Field	Type	Required	Constraints
`name`	`string`	no	min 1, max 40
`color`	`string`	no	—

bash

curl -X PATCH "https://api.zapyflow.com.br/api/conversation-stages/{id}" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Responses

200 — OK
404 — Not found — also returned when the resource belongs to another workspace
409 — Conflict with the current state

DELETE`/api/conversation-stages/{id}`

Delete a sales stage

Required scope: conversation_stages.write

Parameter	In	Required
`id`	path	yes

bash

curl -X DELETE "https://api.zapyflow.com.br/api/conversation-stages/{id}" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
404 — Not found — also returned when the resource belongs to another workspace
409 — Conflict with the current state

GET`/api/conversations`

List the team's conversations, with filters

Required scope: conversations.read

Parameter	In	Required
`page`	query	no
`limit`	query	no
`status`	query	no
`handoffType`	query	no
`aiAgentId`	query	no
`search`	query	no
`assignee`	query	no

bash

curl "https://api.zapyflow.com.br/api/conversations" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK

GET`/api/conversations/{id}`

One conversation in detail

Required scope: conversations.read

Parameter	In	Required
`id`	path	yes

bash

curl "https://api.zapyflow.com.br/api/conversations/{id}" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
404 — Not found — also returned when the resource belongs to another workspace

PATCH`/api/conversations/{id}`

Update a conversation's status or assignee

Required scope: conversations.write

Parameter	In	Required
`id`	path	yes

Request body

Field	Type	Required	Constraints
`status`	`"ACTIVE" \| "RESOLVED" \| "HANDED_OFF"`	no	—
`handoffType`	`string`	no	—
`assignedTo`	`string`	no	—
`assignedToUserId`	`stringnull`	no	—

bash

curl -X PATCH "https://api.zapyflow.com.br/api/conversations/{id}" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Responses

200 — OK
404 — Not found — also returned when the resource belongs to another workspace
422 — Understood, but rejected by a rule

POST`/api/conversations/{id}/ai-insights`

Generate AI insights about a conversation

Required scope: conversations.write

Parameter	In	Required
`id`	path	yes

bash

curl -X POST "https://api.zapyflow.com.br/api/conversations/{id}/ai-insights" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
404 — Not found — also returned when the resource belongs to another workspace

GET`/api/conversations/{id}/messages`

List a conversation's messages, paginated for older history

Required scope: conversations.read

Parameter	In	Required
`limit`	query	no
`cursor`	query	no
`id`	path	yes

bash

curl "https://api.zapyflow.com.br/api/conversations/{id}/messages" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
400 — Malformed request
404 — Not found — also returned when the resource belongs to another workspace

POST`/api/conversations/{id}/messages`

Send a message as a human agent

Required scope: conversations.write

Parameter	In	Required
`id`	path	yes

Request body

Field	Type	Required	Constraints
`content`	`string`	no	min 1
`type`	`"TEXT" \| "AUDIO" \| "IMAGE" \| "VIDEO" \| "DOCUMENT" \| "LOCATION"`	no	—
`mediaUrl`	`string`	no	—
`template`	`object`	no	—
`replyToMessageId`	`string`	no	—
`idempotencyKey`	`string`	no	min 8, max 160
`correlationId`	`string`	no	min 8, max 160

bash

curl -X POST "https://api.zapyflow.com.br/api/conversations/{id}/messages" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Responses

201 — Created
400 — Malformed request
404 — Not found — also returned when the resource belongs to another workspace
409 — Conflict with the current state
503

POST`/api/conversations/{id}/messages/{messageId}/react`

React to a message with an emoji

Required scope: conversations.write

Parameter	In	Required
`id`	path	yes
`messageId`	path	yes

Request body

Field	Type	Required	Constraints
`emoji`	`string`	yes	max 16

bash

curl -X POST "https://api.zapyflow.com.br/api/conversations/{id}/messages/{messageId}/react" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Responses

200 — OK
400 — Malformed request
404 — Not found — also returned when the resource belongs to another workspace

GET`/api/conversations/{id}/template-availability`

Messaging-window availability and quota by template category

Required scope: conversations.read

Parameter	In	Required
`id`	path	yes

bash

curl "https://api.zapyflow.com.br/api/conversations/{id}/template-availability" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
404 — Not found — also returned when the resource belongs to another workspace

POST`/api/conversations/{id}/upload-media`

Upload media (attachment or audio) to send in a conversation

Required scope: conversations.write

Parameter	In	Required
`id`	path	yes

bash

curl -X POST "https://api.zapyflow.com.br/api/conversations/{id}/upload-media" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
400 — Malformed request
404 — Not found — also returned when the resource belongs to another workspace

GET`/api/conversations/{id}/utility-check`

Messaging-window availability and quota by template category

Required scope: conversations.read

Parameter	In	Required
`id`	path	yes

bash

curl "https://api.zapyflow.com.br/api/conversations/{id}/utility-check" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
404 — Not found — also returned when the resource belongs to another workspace

POST`/api/conversations/new`

Start a new conversation with a phone number

Required scope: conversations.write

Request body

Field	Type	Required	Constraints
`content`	`string`	no	min 1
`type`	`"TEXT" \| "AUDIO" \| "IMAGE" \| "VIDEO" \| "DOCUMENT" \| "LOCATION"`	no	—
`mediaUrl`	`string`	no	—
`template`	`object`	no	—
`replyToMessageId`	`string`	no	—
`idempotencyKey`	`string`	no	min 8, max 160
`correlationId`	`string`	no	min 8, max 160
`channelId`	`string`	yes	—
`phoneNumber`	`string`	yes	min 10, max 40

bash

curl -X POST "https://api.zapyflow.com.br/api/conversations/new" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Responses

201 — Created
400 — Malformed request
403 — Forbidden, or the key lacks this scope
409 — Conflict with the current state
503

GET`/api/conversations/overview`

Conversation metrics (7 days) with sparkline and growth

Required scope: conversations.read

bash

curl "https://api.zapyflow.com.br/api/conversations/overview" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK

GET`/api/media-library`

The team's reusable files

Required scope: library.read

bash

curl "https://api.zapyflow.com.br/api/media-library" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK

POST`/api/media-library`

Save a file to the library

Required scope: library.write

Request body

Field	Type	Required	Constraints
`id`	`string`	yes	—
`name`	`string`	yes	—
`url`	`string`	yes	—
`contentType`	`string`	yes	—
`kind`	`"IMAGE" \| "VIDEO" \| "AUDIO" \| "DOCUMENT"`	yes	—
`sizeBytes`	`integer`	yes	—
`usageCount`	`integer`	yes	—

bash

curl -X POST "https://api.zapyflow.com.br/api/media-library" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Responses

201 — Created
400 — Malformed request
409 — Conflict with the current state

PATCH`/api/media-library/{id}`

Rename a file in the library

Required scope: library.write

Parameter	In	Required
`id`	path	yes

Request body

Field	Type	Required	Constraints
`name`	`string`	yes	min 1, max 120

bash

curl -X PATCH "https://api.zapyflow.com.br/api/media-library/{id}" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Responses

200 — OK
404 — Not found — also returned when the resource belongs to another workspace

DELETE`/api/media-library/{id}`

Remove a file from the library

Required scope: library.write

Parameter	In	Required
`id`	path	yes

bash

curl -X DELETE "https://api.zapyflow.com.br/api/media-library/{id}" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
404 — Not found — also returned when the resource belongs to another workspace

POST`/api/media-library/{id}/used`

Record that a library file was sent

Required scope: library.write

Parameter	In	Required
`id`	path	yes

bash

curl -X POST "https://api.zapyflow.com.br/api/media-library/{id}/used" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK

GET`/api/quick-replies`

The team's quick replies

Required scope: library.read

bash

curl "https://api.zapyflow.com.br/api/quick-replies" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK

POST`/api/quick-replies`

Create a quick reply

Required scope: library.write

Request body

Field	Type	Required	Constraints
`shortcut`	`string`	yes	min 1, max 40
`content`	`string`	yes	min 1, max 4000

bash

curl -X POST "https://api.zapyflow.com.br/api/quick-replies" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Responses

201 — Created
409 — Conflict with the current state

DELETE`/api/quick-replies/{id}`

Delete a quick reply

Required scope: library.write

Parameter	In	Required
`id`	path	yes

bash

curl -X DELETE "https://api.zapyflow.com.br/api/quick-replies/{id}" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK
404 — Not found — also returned when the resource belongs to another workspace

POST`/api/quick-replies/{id}/used`

Record that a quick reply was used

Required scope: library.write

Parameter	In	Required
`id`	path	yes

bash

curl -X POST "https://api.zapyflow.com.br/api/quick-replies/{id}/used" \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY"

Responses

200 — OK

Conversations

GET/api/conversation-stages

POST/api/conversation-stages

PATCH/api/conversation-stages/{id}

DELETE/api/conversation-stages/{id}

GET/api/conversations

GET/api/conversations/{id}

PATCH/api/conversations/{id}

POST/api/conversations/{id}/ai-insights

GET/api/conversations/{id}/messages

POST/api/conversations/{id}/messages

POST/api/conversations/{id}/messages/{messageId}/react

GET/api/conversations/{id}/template-availability

POST/api/conversations/{id}/upload-media

GET/api/conversations/{id}/utility-check

POST/api/conversations/new

GET/api/conversations/overview

GET/api/media-library

POST/api/media-library

PATCH/api/media-library/{id}

DELETE/api/media-library/{id}

POST/api/media-library/{id}/used

GET/api/quick-replies

POST/api/quick-replies

DELETE/api/quick-replies/{id}

POST/api/quick-replies/{id}/used

GET`/api/conversation-stages`

POST`/api/conversation-stages`

PATCH`/api/conversation-stages/{id}`

DELETE`/api/conversation-stages/{id}`

GET`/api/conversations`

GET`/api/conversations/{id}`

PATCH`/api/conversations/{id}`

POST`/api/conversations/{id}/ai-insights`

GET`/api/conversations/{id}/messages`

POST`/api/conversations/{id}/messages`

POST`/api/conversations/{id}/messages/{messageId}/react`

GET`/api/conversations/{id}/template-availability`

POST`/api/conversations/{id}/upload-media`

GET`/api/conversations/{id}/utility-check`

POST`/api/conversations/new`

GET`/api/conversations/overview`

GET`/api/media-library`

POST`/api/media-library`

PATCH`/api/media-library/{id}`

DELETE`/api/media-library/{id}`

POST`/api/media-library/{id}/used`

GET`/api/quick-replies`

POST`/api/quick-replies`

DELETE`/api/quick-replies/{id}`

POST`/api/quick-replies/{id}/used`