Conversations

Conversaciones y mensajes

GET`/api/conversation-stages`

Etapas comerciales del equipo

Ámbito requerido: conversations.read

bash

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

Respuestas

200 — OK

POST`/api/conversation-stages`

Crear una etapa comercial

Ámbito requerido: conversation_stages.write

Cuerpo de la petición

Campo	Tipo	Obligatorio	Restricciones
`name`	`string`	sí	min 1, max 40
`color`	`string`	sí	—

bash

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

Respuestas

201 — Creado
409 — Conflicto con el estado actual
422 — Entendido, pero rechazado por una regla

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

Renombrar o recolorear una etapa comercial

Ámbito requerido: conversation_stages.write

Parámetro	Dónde	Obligatorio
`id`	path	sí

Cuerpo de la petición

Campo	Tipo	Obligatorio	Restricciones
`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 '{ ... }'

Respuestas

200 — OK
404 — No encontrado — también es la respuesta cuando el recurso es de otro workspace
409 — Conflicto con el estado actual

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

Eliminar una etapa comercial

Ámbito requerido: conversation_stages.write

Parámetro	Dónde	Obligatorio
`id`	path	sí

bash

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

Respuestas

200 — OK
404 — No encontrado — también es la respuesta cuando el recurso es de otro workspace
409 — Conflicto con el estado actual

GET`/api/conversations`

Listar las conversaciones del equipo, con filtros

Ámbito requerido: conversations.read

Parámetro	Dónde	Obligatorio
`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"

Respuestas

200 — OK

GET`/api/conversations/{id}`

Detalles de una conversación

Ámbito requerido: conversations.read

Parámetro	Dónde	Obligatorio
`id`	path	sí

bash

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

Respuestas

200 — OK
404 — No encontrado — también es la respuesta cuando el recurso es de otro workspace

PATCH`/api/conversations/{id}`

Actualizar el estado o el responsable de una conversación

Ámbito requerido: conversations.write

Parámetro	Dónde	Obligatorio
`id`	path	sí

Cuerpo de la petición

Campo	Tipo	Obligatorio	Restricciones
`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 '{ ... }'

Respuestas

200 — OK
404 — No encontrado — también es la respuesta cuando el recurso es de otro workspace
422 — Entendido, pero rechazado por una regla

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

Generar análisis con IA sobre una conversación

Ámbito requerido: conversations.write

Parámetro	Dónde	Obligatorio
`id`	path	sí

bash

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

Respuestas

200 — OK
404 — No encontrado — también es la respuesta cuando el recurso es de otro workspace

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

Listar los mensajes de una conversación, paginado para el historial antiguo

Ámbito requerido: conversations.read

Parámetro	Dónde	Obligatorio
`limit`	query	no
`cursor`	query	no
`id`	path	sí

bash

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

Respuestas

200 — OK
400 — Petición malformada
404 — No encontrado — también es la respuesta cuando el recurso es de otro workspace

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

Enviar un mensaje como agente humano

Ámbito requerido: conversations.write

Parámetro	Dónde	Obligatorio
`id`	path	sí

Cuerpo de la petición

Campo	Tipo	Obligatorio	Restricciones
`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 '{ ... }'

Respuestas

201 — Creado
400 — Petición malformada
404 — No encontrado — también es la respuesta cuando el recurso es de otro workspace
409 — Conflicto con el estado actual
503

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

Reaccionar a un mensaje con un emoji

Ámbito requerido: conversations.write

Parámetro	Dónde	Obligatorio
`id`	path	sí
`messageId`	path	sí

Cuerpo de la petición

Campo	Tipo	Obligatorio	Restricciones
`emoji`	`string`	sí	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 '{ ... }'

Respuestas

200 — OK
400 — Petición malformada
404 — No encontrado — también es la respuesta cuando el recurso es de otro workspace

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

Disponibilidad de ventana y cuotas por categoría de plantilla

Ámbito requerido: conversations.read

Parámetro	Dónde	Obligatorio
`id`	path	sí

bash

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

Respuestas

200 — OK
404 — No encontrado — también es la respuesta cuando el recurso es de otro workspace

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

Sube contenido (adjunto o audio) para enviar en una conversación

Ámbito requerido: conversations.write

Parámetro	Dónde	Obligatorio
`id`	path	sí

bash

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

Respuestas

200 — OK
400 — Petición malformada
404 — No encontrado — también es la respuesta cuando el recurso es de otro workspace

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

Disponibilidad de ventana y cuotas por categoría de plantilla

Ámbito requerido: conversations.read

Parámetro	Dónde	Obligatorio
`id`	path	sí

bash

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

Respuestas

200 — OK
404 — No encontrado — también es la respuesta cuando el recurso es de otro workspace

POST`/api/conversations/new`

Iniciar una conversación nueva con un número

Ámbito requerido: conversations.write

Cuerpo de la petición

Campo	Tipo	Obligatorio	Restricciones
`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`	sí	—
`phoneNumber`	`string`	sí	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 '{ ... }'

Respuestas

201 — Creado
400 — Petición malformada
403 — Prohibido, o la clave no tiene este ámbito
409 — Conflicto con el estado actual
503

GET`/api/conversations/overview`

Métricas de conversaciones (7 días) con sparkline y crecimiento

Ámbito requerido: conversations.read

bash

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

Respuestas

200 — OK

GET`/api/media-library`

Archivos reutilizables del equipo

Ámbito requerido: library.read

bash

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

Respuestas

200 — OK

POST`/api/media-library`

Guardar un archivo en la biblioteca

Ámbito requerido: library.write

Cuerpo de la petición

Campo	Tipo	Obligatorio	Restricciones
`id`	`string`	sí	—
`name`	`string`	sí	—
`url`	`string`	sí	—
`contentType`	`string`	sí	—
`kind`	`"IMAGE" \| "VIDEO" \| "AUDIO" \| "DOCUMENT"`	sí	—
`sizeBytes`	`integer`	sí	—
`usageCount`	`integer`	sí	—

bash

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

Respuestas

201 — Creado
400 — Petición malformada
409 — Conflicto con el estado actual

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

Renombrar un archivo de la biblioteca

Ámbito requerido: library.write

Parámetro	Dónde	Obligatorio
`id`	path	sí

Cuerpo de la petición

Campo	Tipo	Obligatorio	Restricciones
`name`	`string`	sí	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 '{ ... }'

Respuestas

200 — OK
404 — No encontrado — también es la respuesta cuando el recurso es de otro workspace

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

Quitar un archivo de la biblioteca

Ámbito requerido: library.write

Parámetro	Dónde	Obligatorio
`id`	path	sí

bash

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

Respuestas

200 — OK
404 — No encontrado — también es la respuesta cuando el recurso es de otro workspace

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

Registrar el envío de un archivo de la biblioteca

Ámbito requerido: library.write

Parámetro	Dónde	Obligatorio
`id`	path	sí

bash

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

Respuestas

200 — OK

GET`/api/quick-replies`

Respuestas rápidas del equipo

Ámbito requerido: library.read

bash

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

Respuestas

200 — OK

POST`/api/quick-replies`

Crear una respuesta rápida

Ámbito requerido: library.write

Cuerpo de la petición

Campo	Tipo	Obligatorio	Restricciones
`shortcut`	`string`	sí	min 1, max 40
`content`	`string`	sí	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 '{ ... }'

Respuestas

201 — Creado
409 — Conflicto con el estado actual

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

Eliminar una respuesta rápida

Ámbito requerido: library.write

Parámetro	Dónde	Obligatorio
`id`	path	sí

bash

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

Respuestas

200 — OK
404 — No encontrado — también es la respuesta cuando el recurso es de otro workspace

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

Registrar el uso de una respuesta rápida

Ámbito requerido: library.write

Parámetro	Dónde	Obligatorio
`id`	path	sí

bash

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

Respuestas

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`