Simplidy API
Copies this version's full documentation as Markdown, ready to paste into Claude, ChatGPT or Codex.
Read and reply to your business's official WhatsApp conversations over HTTP, get webhook notifications or connect an AI agent through MCP. All in JSON.
https://api.simplidy.comVersioning
The version is in the path (/v1, /v2...) and each one works separately: integrations on one version are not affected when another ships. Every response includes the X-Simplidy-Api-Version header. Use the selector at the top to see the docs for each version.
| Version | Address | Status | Released | Works until |
|---|---|---|---|---|
| v1 | https://api.simplidy.com/v1 | current | 11/18/2026 | no retirement date |
- Within v1 only backward-compatible changes ship: new fields and endpoints, never removals or changed meanings.
- Breaking changes ship in a new version (/v2), and v1 keeps working for at least 6 months after notice.
- Ignore fields you don't recognize: they may appear at any time.
- Webhooks follow the same rule: each webhook picks its format version when registered and keeps receiving in it.
- Whenever a version is being retired, the notice shows here with the date, at least 6 months in advance.
Authentication
Create a token in Settings > API & MCP and send it on every call. "read" reads; "write" can also reply and change conversations. What you send shows in the chat with the token's name.
curl https://api.simplidy.com/v1/conversations?filter=agent \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Accept: application/json"
How to attend (for AI agents)
- List the queue: GET /conversations?filter=agent.
- Open each conversation (GET /conversations/{id}) and read the messages, notes and knowledge base.
- Reply with POST /conversations/{id}/messages if window_open is true; otherwise, use an approved template.
- Don't reply to conversations with taken_over_by set: a team member took over.
- Only use facts from the knowledge base. If the answer isn't there, add the "Precisa de humano" tag.
- When the matter is done, mark it resolved (PATCH with resolved=true).
Objects
Dates in ISO 8601 (UTC). Bodies and responses in JSON (UTF-8).
Conversation
| id | string (uuid) | Conversation identifier. It is the {id} in the paths. |
| name | string | Saved name or WhatsApp profile name. |
| phone | string | Phone in international format (+55...). |
| account | object | Business WhatsApp number that received the conversation (id and name). |
| last_message | string|null | Preview of the last message. |
| last_message_at | string (ISO 8601, UTC) | Date of the last message. |
| waiting_reply | boolean | The last message is from the contact and the conversation is not resolved. |
| unread | integer | Messages not read by the team. |
| window_open | boolean | 24-hour window open: free text can be sent. |
| window_closes_at | string|null | When the 24-hour window closes. |
| taken_over_by | string|null | Name of the person who took over. When set, the agent must not reply. |
| resolved | boolean | Conversation resolved. |
| tags | string[] | Tags. |
| notes | string|null | Internal notes about the contact. |
Message
| id | integer | Message identifier (use in reply_to_message_id and before_id). |
| from | contact | business | Who sent it. |
| by | string | Business messages only: person, token name (agent), "IA de reserva · model" or "celular" (phone). |
| type | string | text, image, video, audio, document, sticker, location, template... |
| text | string | Text or caption. |
| media | string | File name, when there is media. |
| template | string | Template name, when a template was sent. |
| reply_to | object | Quoted message (id and text). |
| status | string | Business messages only: pending, sent, delivered, read or failed. |
| sent_at | string (ISO 8601, UTC) | Sent date. |
Knowledge base item
| id | integer | Item identifier. |
| account_id | integer|null | Number the item belongs to; null applies to all. |
| title | string | Title. |
| content | string | Text with the information. |
| images | object[] | Item photos (index and name). Send with knowledge-image. |
Endpoints
The conversation {id} is the uuid returned in the lists.
Reading (read permission)
GET
/v1/me
Who am I
Who owns the token and its permissions.
Example
curl "https://api.simplidy.com/v1/me" \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Accept: application/json"
Response 200
{
"user": {
"name": "Micaias",
"email": "voce@empresa.com"
},
"token": {
"name": "Claude",
"abilities": [
"read",
"write"
]
}
}
GET
/v1/accounts
Connected numbers
Connected WhatsApp numbers.
Example
curl "https://api.simplidy.com/v1/accounts" \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Accept: application/json"
Response 200
{
"accounts": [
{
"id": 1,
"name": "Atendimento",
"display_phone": "+55 11 98765-0000",
"status": "connected"
}
]
}
GET
/v1/conversations
List conversations
Conversations from newest to oldest. Without a filter, returns the agent queue.
Query parameters
| filter | string | agent (default: waiting for a reply and not taken over), awaiting, unread, human, resolved, expiring (window closes in under 2 h) or all. |
| account_id | integer | Only conversations of this number. |
| tag | string | Only conversations with this tag. |
| search | string | Search by name or phone. |
| limit | integer | 1 to 100 (default 30). |
Example
curl "https://api.simplidy.com/v1/conversations?filter=agent&limit=20" \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Accept: application/json"
Response 200
{
"conversations": [
{
"id": "019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d",
"name": "Maria Souza",
"phone": "+5511987650001",
"account": {
"id": 1,
"name": "Atendimento"
},
"last_message": "Que horas vocês abrem amanhã?",
"last_message_at": "2026-11-19T14:02:11+00:00",
"waiting_reply": true,
"unread": 1,
"window_open": true,
"window_closes_at": "2026-11-20T14:02:11+00:00",
"taken_over_by": null,
"resolved": false,
"tags": [
"Orçamento"
],
"notes": "Prefere contato de manhã"
}
]
}
GET
/v1/conversations/{id}
Open conversation
Conversation with notes, tags, 24-hour window, latest messages and the number's knowledge base.
Query parameters
| limit | integer | How many messages to return (default 40, max 100). |
Example
curl "https://api.simplidy.com/v1/conversations/019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d" \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Accept: application/json"
Response 200
{
"conversation": {
"id": "019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d",
"name": "Maria Souza",
"phone": "+5511987650001",
"account": {
"id": 1,
"name": "Atendimento"
},
"last_message": "Que horas vocês abrem amanhã?",
"last_message_at": "2026-11-19T14:02:11+00:00",
"waiting_reply": true,
"unread": 1,
"window_open": true,
"window_closes_at": "2026-11-20T14:02:11+00:00",
"taken_over_by": null,
"resolved": false,
"tags": [
"Orçamento"
],
"notes": "Prefere contato de manhã"
},
"messages": [
{
"id": 812,
"from": "contact",
"type": "text",
"text": "Que horas vocês abrem amanhã?",
"sent_at": "2026-11-19T14:02:11+00:00"
}
],
"knowledge": [
{
"id": 7,
"account_id": null,
"title": "Horário de funcionamento",
"content": "Segunda a sexta, das 9h às 18h. Sábado, das 9h às 13h.",
"images": [
{
"index": 0,
"name": "fachada.jpg"
}
]
}
]
}
GET
/v1/conversations/{id}/messages
Messages
Messages in chronological order. To fetch older ones, pass in before_id the id of the first one you already have.
Query parameters
| limit | integer | How many messages to return (default 40, max 100). |
| before_id | integer | Only messages before this one. |
Example
curl "https://api.simplidy.com/v1/conversations/019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d/messages?limit=40&before_id=800" \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Accept: application/json"
Response 200
{
"messages": [
{
"id": 812,
"from": "contact",
"type": "text",
"text": "Que horas vocês abrem amanhã?",
"sent_at": "2026-11-19T14:02:11+00:00"
},
{
"id": 813,
"from": "business",
"by": "Claude",
"type": "text",
"text": "Olá, Maria! Abrimos às 9h.",
"reply_to": {
"id": 812,
"text": "Que horas vocês abrem amanhã?"
},
"status": "sent",
"sent_at": "2026-11-19T14:03:40+00:00"
}
]
}
GET
/v1/accounts/{id}/templates
Approved templates
Approved templates of the number (name, language, text, variables). supported=false: the template has a media or variable header and can't be sent through the API.
Example
curl "https://api.simplidy.com/v1/accounts/1/templates" \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Accept: application/json"
Response 200
{
"templates": [
{
"name": "order_update",
"language": "pt_BR",
"category": "UTILITY",
"body": "Olá {{1}}, seu pedido {{2}} saiu para entrega.",
"variables": 2,
"supported": true
}
],
"error": null
}
GET
/v1/knowledge
Knowledge base
Active knowledge base (general and per number), with each item's photos.
Query parameters
| account_id | integer | Includes this number's items besides the general ones. |
Example
curl "https://api.simplidy.com/v1/knowledge" \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Accept: application/json"
Response 200
{
"knowledge": [
{
"id": 7,
"account_id": null,
"title": "Horário de funcionamento",
"content": "Segunda a sexta, das 9h às 18h. Sábado, das 9h às 13h.",
"images": [
{
"index": 0,
"name": "fachada.jpg"
}
]
}
]
}
Sending and handling (write permission)
POST
/v1/conversations/{id}/messages
Reply with text
Replies with text. Only works with the 24-hour window open (window_open); outside it, use a template.
Body (JSON)
| text* | string | Reply text (up to 4096 characters). |
| reply_to_message_id | integer | Id of the message to quote. |
Example
curl -X POST "https://api.simplidy.com/v1/conversations/019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d/messages" \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"text":"Olá, Maria! Abrimos às 9h.","reply_to_message_id":812}'
Response 201
{
"message": {
"id": 813,
"from": "business",
"by": "Claude",
"type": "text",
"text": "Olá, Maria! Abrimos às 9h.",
"reply_to": {
"id": 812,
"text": "Que horas vocês abrem amanhã?"
},
"status": "sent",
"sent_at": "2026-11-19T14:03:40+00:00"
}
}
POST
/v1/conversations/{id}/template
Send template
Sends an approved template (works outside the window).
Body (JSON)
| name* | string | Template name. |
| language* | string | Template language, e.g. pt_BR. |
| params | string[] | Values for variables {{1}}, {{2}}..., in order. |
Example
curl -X POST "https://api.simplidy.com/v1/conversations/019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d/template" \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"name":"order_update","language":"pt_BR","params":["Maria","#2381"]}'
Response 201
{
"message": {
"id": 814,
"from": "business",
"by": "Claude",
"type": "template",
"text": "Olá Maria, seu pedido #2381 saiu para entrega.",
"reply_to": null,
"status": "sent",
"sent_at": "2026-11-19T14:03:40+00:00",
"template": "order_update"
}
}
POST
/v1/conversations/{id}/knowledge-image
Send knowledge photo
Sends the contact a photo from a knowledge base item.
Body (JSON)
| knowledge_id* | integer | Knowledge item id. |
| image_index | integer | Photo index in the item (default 0). |
| caption | string | Caption. |
Example
curl -X POST "https://api.simplidy.com/v1/conversations/019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d/knowledge-image" \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"knowledge_id":7,"image_index":0,"caption":"Nossa fachada"}'
Response 201
{
"message": {
"id": 815,
"from": "business",
"by": "Claude",
"type": "image",
"text": "Nossa fachada",
"reply_to": null,
"status": "sent",
"sent_at": "2026-11-19T14:03:40+00:00",
"media": "fachada.jpg"
}
}
PATCH
/v1/conversations/{id}
Update handling
Updates handling: notes, resolve, take over, tags. Send only the fields you want to change.
Body (JSON)
| notes | string|null | Replaces the notes (read first so nothing is lost). |
| resolved | boolean | true resolves; false reopens. |
| takeover | boolean | true: the token owner takes over and the agent stops; false: hands back to the agent. |
| add_tags | string[] | Tags to add (created if they don't exist). |
| remove_tags | string[] | Tags to remove. |
Example
curl -X PATCH "https://api.simplidy.com/v1/conversations/019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d" \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"resolved":true,"notes":"Prefere contato de manhã. Agendou para sexta.","add_tags":["Agendou"],"remove_tags":["Precisa de humano"]}'
Response 200
{
"conversation": {
"id": "019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d",
"name": "Maria Souza",
"phone": "+5511987650001",
"account": {
"id": 1,
"name": "Atendimento"
},
"last_message": "Que horas vocês abrem amanhã?",
"last_message_at": "2026-11-19T14:02:11+00:00",
"waiting_reply": false,
"unread": 1,
"window_open": true,
"window_closes_at": "2026-11-20T14:02:11+00:00",
"taken_over_by": null,
"resolved": true,
"tags": [
"Orçamento",
"Agendou"
],
"notes": "Prefere contato de manhã. Agendou para sexta."
}
}
POST
/v1/knowledge
Create knowledge item
Creates a knowledge item (requires "Fill with AI" on). If review is on, the item starts disabled (enabled=false) until someone approves it.
Body (JSON)
| title* | string | Title (up to 150 characters). |
| content* | string | Text (up to 5000 characters). |
| account_id | integer|null | Number the item belongs to; empty applies to all. |
Example
curl -X POST "https://api.simplidy.com/v1/knowledge" \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"title":"Horário de funcionamento","content":"Segunda a sexta, das 9h às 18h.","account_id":null}'
Response 201
{
"knowledge": {
"id": 7,
"account_id": null,
"title": "Horário de funcionamento",
"content": "Segunda a sexta, das 9h às 18h.",
"images": []
},
"enabled": true
}
PUT
/v1/knowledge/{id}
Update knowledge item
Updates a knowledge base item.
Body (JSON)
| title* | string | Title (up to 150 characters). |
| content* | string | Text (up to 5000 characters). |
| account_id | integer|null | Number the item belongs to; empty applies to all. |
Example
curl -X PUT "https://api.simplidy.com/v1/knowledge/7" \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"title":"Horário de funcionamento","content":"Segunda a sábado, das 9h às 18h."}'
Response 200
{
"knowledge": {
"id": 7,
"account_id": null,
"title": "Horário de funcionamento",
"content": "Segunda a sábado, das 9h às 18h.",
"images": [
{
"index": 0,
"name": "fachada.jpg"
}
]
},
"enabled": true
}
DELETE
/v1/knowledge/{id}
Delete knowledge item
Deletes a knowledge base item.
Example
curl -X DELETE "https://api.simplidy.com/v1/knowledge/7" \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Accept: application/json"
Response 200
{
"deleted": 7
}
Webhooks
Register in Settings > Webhooks. Each notification is a JSON POST signed with the webhook secret.
POST https://seu-sistema.com/webhooks/simplidy Content-Type: application/json X-Simplidy-Event: message.received X-Simplidy-Api-Version: 1 X-Simplidy-Delivery: 6f1c2b9e-3d4a-4b8e-9f10-2a3b4c5d6e7f X-Simplidy-Signature: sha256=<hmac-sha256 do corpo com o segredo>
Verify the signature and reply with HTTP 2xx within 5 seconds. After 20 failures in a row the webhook is paused.
// PHP
$ok = hash_equals('sha256='.hash_hmac('sha256', $corpo, $segredo), $_SERVER['HTTP_X_SIMPLIDY_SIGNATURE']);
// Node.js
const ok = crypto.timingSafeEqual(Buffer.from('sha256=' + crypto.createHmac('sha256', segredo).update(corpo).digest('hex')), Buffer.from(req.headers['x-simplidy-signature']));
message.received
Message received from the contact
{
"id": "6f1c2b9e-3d4a-4b8e-9f10-2a3b4c5d6e7f",
"event": "message.received",
"created_at": "2026-11-19T14:02:12+00:00",
"data": {
"conversation": {
"id": "019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d",
"name": "Maria Souza",
"phone": "+5511987650001",
"account": {
"id": 1,
"name": "Atendimento"
},
"last_message": "Que horas vocês abrem amanhã?",
"last_message_at": "2026-11-19T14:02:11+00:00",
"waiting_reply": true,
"unread": 1,
"window_open": true,
"window_closes_at": "2026-11-20T14:02:11+00:00",
"taken_over_by": null,
"resolved": false,
"tags": [
"Orçamento"
],
"notes": "Prefere contato de manhã"
},
"message": {
"id": 812,
"from": "contact",
"type": "text",
"text": "Que horas vocês abrem amanhã?",
"sent_at": "2026-11-19T14:02:11+00:00"
}
}
}
message.sent
Message sent (team, agent or phone)
{
"id": "6f1c2b9e-3d4a-4b8e-9f10-2a3b4c5d6e7f",
"event": "message.sent",
"created_at": "2026-11-19T14:02:12+00:00",
"data": {
"conversation": {
"id": "019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d",
"name": "Maria Souza",
"phone": "+5511987650001",
"account": {
"id": 1,
"name": "Atendimento"
},
"last_message": "Olá, Maria! Abrimos às 9h.",
"last_message_at": "2026-11-19T14:02:11+00:00",
"waiting_reply": false,
"unread": 0,
"window_open": true,
"window_closes_at": "2026-11-20T14:02:11+00:00",
"taken_over_by": null,
"resolved": false,
"tags": [
"Orçamento"
],
"notes": "Prefere contato de manhã"
},
"message": {
"id": 813,
"from": "business",
"by": "Claude",
"type": "text",
"text": "Olá, Maria! Abrimos às 9h.",
"reply_to": {
"id": 812,
"text": "Que horas vocês abrem amanhã?"
},
"status": "sent",
"sent_at": "2026-11-19T14:03:40+00:00"
}
}
}
message.status
Message status (delivered, read, failed)
{
"id": "6f1c2b9e-3d4a-4b8e-9f10-2a3b4c5d6e7f",
"event": "message.status",
"created_at": "2026-11-19T14:02:12+00:00",
"data": {
"conversation": {
"id": "019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d",
"name": "Maria Souza",
"phone": "+5511987650001",
"account": {
"id": 1,
"name": "Atendimento"
},
"last_message": "Que horas vocês abrem amanhã?",
"last_message_at": "2026-11-19T14:02:11+00:00",
"waiting_reply": false,
"unread": 0,
"window_open": true,
"window_closes_at": "2026-11-20T14:02:11+00:00",
"taken_over_by": null,
"resolved": false,
"tags": [
"Orçamento"
],
"notes": "Prefere contato de manhã"
},
"message": {
"id": 813,
"from": "business",
"by": "Claude",
"type": "text",
"text": "Olá, Maria! Abrimos às 9h.",
"reply_to": {
"id": 812,
"text": "Que horas vocês abrem amanhã?"
},
"status": "read",
"sent_at": "2026-11-19T14:03:40+00:00"
}
}
}
conversation.event
Conversation (take over, resolve, reopen, notes, tags, backup AI)
{
"id": "6f1c2b9e-3d4a-4b8e-9f10-2a3b4c5d6e7f",
"event": "conversation.event",
"created_at": "2026-11-19T14:02:12+00:00",
"data": {
"type": "resolved",
"by": "Claude",
"details": null,
"conversation": {
"id": "019a4c2e-7b1d-7f3a-9c2e-1d2f3a4b5c6d",
"name": "Maria Souza",
"phone": "+5511987650001",
"account": {
"id": 1,
"name": "Atendimento"
},
"last_message": "Que horas vocês abrem amanhã?",
"last_message_at": "2026-11-19T14:02:11+00:00",
"waiting_reply": false,
"unread": 1,
"window_open": true,
"window_closes_at": "2026-11-20T14:02:11+00:00",
"taken_over_by": null,
"resolved": true,
"tags": [
"Orçamento"
],
"notes": "Prefere contato de manhã"
}
}
}
conversation.event types (data.type)
takeover
Someone took over the conversation.
released
Handed back to the agent.
resolved
Resolved.
reopened
Reopened.
reopened_by_contact
Reopened because the contact wrote again.
notes
Notes changed.
tag_added
Tag added (details.tag).
tag_removed
Tag removed (details.tag).
ai_replied
The backup AI replied.
ai_failed
The backup AI failed (details.error).
MCP
For Claude, Codex or another agent: the MCP server provides the tools below, the "simplidy://guia" guide (how the CRM works) and the "attend-whatsapp" shortcut.
With header: https://api.simplidy.com/mcp + Authorization: Bearer SEU_TOKEN
Without header (claude.ai): https://api.simplidy.com/mcp/t/SEU_TOKEN
Recommended: a Haiku subagent watching the queue
To avoid spending the main model just checking for new messages, keep a subagent on Claude Haiku 5.5 (cheap and fast) calling list-conversations with filter "agent" every 1 or 2 minutes. When there is a conversation in the queue, it hands the id to the main agent, which reads and replies.
Subagente vigia (modelo: claude-haiku-5-5) A cada 1 a 2 minutos, chame list-conversations com filter "agent" e limit 20. - Fila vazia: não faça nada e espere a próxima rodada. - Com conversas: devolva ao agente principal só os ids (uuid) e a última mensagem de cada uma. Não responda clientes, não mude nada e não leia conversas inteiras: quem atende é o agente principal.
| Tool | Arguments (* required) | Description |
|---|---|---|
| list-conversations | filter, account_id, tag, search, limit | Conversation queue and search. |
| get-conversation | conversation_id*, limit | Full conversation with notes, tags and knowledge base. |
| send-message | conversation_id*, text*, reply_to_message_id | Replies with text. |
| send-template | conversation_id*, name*, language*, params | Sends an approved template. |
| send-knowledge-image | conversation_id*, knowledge_id*, image_index, caption | Sends a knowledge base photo. |
| list-templates | account_id* | A number's approved templates. |
| update-conversation | conversation_id*, notes, resolved, takeover, add_tags, remove_tags | Notes, resolve, take over and tags. |
| get-knowledge | account_id | Knowledge base. |
| save-knowledge | id, title*, content*, account_id | Saves a knowledge base item (with "Fill with AI" on). |
| delete-knowledge | id* | Deletes a knowledge base item. |
| list-accounts | — | Connected numbers. |
Errors and limits
200 / 201Success (201 when something was created or sent).401Missing, invalid or expired token.403The token lacks the permission (read/write) or the feature is off.404Conversation, item or number not found.422Invalid data or Meta refused it (e.g. 24-hour window closed). The message explains why.429Too many calls: up to 300 per minute per user, 60 sends per minute.5xxError on our side or Meta's. Try again in a few seconds.401
{
"message": "Unauthenticated."
}
422 (validation)
{
"message": "The text field is required.",
"errors": {
"text": [
"The text field is required."
]
}
}
422 (sending)
{
"message": "A janela de 24 horas está fechada. Envie um modelo aprovado."
}