Simplidy
v1 current

Simplidy API

View as Markdown

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.

Base URL: https://api.simplidy.com

Versioning

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.

VersionAddressStatusReleasedWorks 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)

  1. List the queue: GET /conversations?filter=agent.
  2. Open each conversation (GET /conversations/{id}) and read the messages, notes and knowledge base.
  3. Reply with POST /conversations/{id}/messages if window_open is true; otherwise, use an approved template.
  4. Don't reply to conversations with taken_over_by set: a team member took over.
  5. Only use facts from the knowledge base. If the answer isn't there, add the "Precisa de humano" tag.
  6. 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 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 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

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}

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

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

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

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

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}

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

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}

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}

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.
ToolArguments (* 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."
}