> ## Documentation Index > Fetch the complete documentation index at: https://docs.ararahq.com/llms.txt > Use this file to discover all available pages before exploring further. # Acionar automação pelo link > Link próprio de uma automação com gatilho `webhook`. Não usa chave de API: o `token` na URL é a credencial. Trate o link como segredo. O mesmo link aceita dois corpos: - Com `phone`: inicia uma execução (`202`). - Com `referenceId` e `status` na raiz: atualiza o pagamento de uma cobrança já enviada (`200`), e a execução segue pelo ramo `paid` ou `unpaid` do passo `wait_payment`. Corpo de até 64 KB. Guia completo em [Link da automação e pagamento](/automacoes-webhook). ## OpenAPI ````yaml /openapi.yaml post /hooks/a/{token} openapi: 3.0.3 info: title: API da Arara description: > API REST da Arara para WhatsApp Business: mensagens, templates, campanhas, contatos, conversas, formulários, automações, smart links e carteira. Esta especificação cobre só os endpoints que aceitam **chave de API** (`Authorization: Bearer ara_live_...`). Rotas usadas apenas pelo painel (gestão de chaves, configuração do webhook, pagamentos e perfil pessoal) ficam de fora. ## Autenticação Header `Authorization: Bearer ara_live_...`. Crie a chave em https://app.ararahq.com/dashboard/apikeys. As chaves são sempre LIVE: mensagens são entregues de verdade e o custo sai da carteira. ## Permissões da chave Chave criada sem permissões explícitas tem acesso total (`ADMIN`). Chave com permissões restritas só alcança: - `READ`: `GET` em `/v1/messages`, `/v1/campaigns`, `/v1/templates`, `/v1/flows`, `/v1/automations` e `/v1/organizations/me/numbers`. - `MESSAGES_SEND`: escrita em `/v1/messages/**`, `POST /v1/media/upload` e `POST /v1/flows/{id}/test`. - `TEMPLATES_WRITE`: escrita em `/v1/templates/**` e `/v1/flows/**`. - `CAMPAIGNS_SEND`: escrita em `/v1/campaigns/**`. - `CONTACTS_WRITE`: escrita em `/v1/contacts/**`. - `AUTOMATIONS_MANAGE`: escrita em `/v1/automations/**`. - `WEBHOOKS_MANAGE`: escrita em `/webhook/**`. Qualquer outra rota exige `ADMIN`. Fora do escopo, a resposta é `403`. ## Rate limit Por usuário da chave: 1.200 leituras (`GET`) por minuto e 3.000 escritas por minuto. Toda resposta traz `X-RateLimit-Remaining`. Acima do limite: `429` com `Retry-After` e `error.code = RATE_LIMIT_EXCEEDED`. O envio tem limites próprios (`SEND_RATE_LIMITED`, `BATCH_BUSY`, `MARKETING_FREQUENCY_EXCEEDED`). ## Formato de erro ```json { "error": { "code": "ERROR_CODE", "message": "Descrição", "details": {} } } ``` Exceções: falha de autenticação (`401`, `403` e `503` do filtro de chave) volta no formato padrão do Spring (`timestamp`, `status`, `error`, `path`, sem `code`), e alguns `404` e `403` voltam sem corpo. version: 2.1.0 contact: name: AraraHQ url: https://ararahq.com email: oi@ararahq.com servers: - url: https://api.ararahq.com description: Produção security: - bearerAuth: [] tags: - name: Mensagens description: Envio, consulta e histórico de mensagens de WhatsApp, e upload de mídia. - name: Conversas description: >- Conversas com cada telefone, resposta dentro da janela de 24h e situação da janela. - name: Templates description: Criação, listagem, status de aprovação e métricas de templates. - name: Campanhas description: >- Envio do mesmo template para muitos contatos, com estimativa, agendamento, cancelamento e teste A/B. - name: Contatos description: Base de contatos da organização e direitos do titular (LGPD). - name: Opt-out description: Registro e consulta de quem pediu para não receber mensagens. - name: Formulários description: >- Formulários nativos do WhatsApp (Flows) e as respostas recebidas. Disponíveis do plano Voo para cima. - name: Automações description: >- Sequências de passos que rodam sozinhas para cada contato que entra por um gatilho. Exigem plano com recuperação de receita. - name: Smart Links description: Links wa.me rastreáveis, com QR code. - name: Números description: >- Números de WhatsApp da organização e o perfil comercial exibido no WhatsApp. - name: Carteira description: Saldo, extrato, recarga automática e preços. - name: Consulta de telefone description: Consulta de tipo de linha e de WhatsApp de um número (cobrada). - name: Recuperação description: Endpoint de recuperação de receita (carrinho abandonado, Pix, boleto). - name: Conta description: Identidade da chave, plano da organização e status da API. paths: /hooks/a/{token}: post: tags: - Automações summary: Acionar automação pelo link description: | Link próprio de uma automação com gatilho `webhook`. Não usa chave de API: o `token` na URL é a credencial. Trate o link como segredo. O mesmo link aceita dois corpos: - Com `phone`: inicia uma execução (`202`). - Com `referenceId` e `status` na raiz: atualiza o pagamento de uma cobrança já enviada (`200`), e a execução segue pelo ramo `paid` ou `unpaid` do passo `wait_payment`. Corpo de até 64 KB. Guia completo em [Link da automação e pagamento](/automacoes-webhook). operationId: triggerAutomationHook parameters: - in: path name: token required: true schema: type: string description: >- Token do link (`ara_hook_...`), copiado da tela da automação ou do campo `hook.url`. - in: header name: X-Arara-Signature required: false schema: type: string description: >- Assinatura do corpo. Obrigatória quando a assinatura do link está ligada. - in: header name: Idempotency-Key required: false schema: type: string description: >- Evita iniciar a mesma execução duas vezes. Use o id do evento no seu sistema (ex. o número do pedido). requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/HookStartRequest' - $ref: '#/components/schemas/HookPaymentUpdateRequest' examples: iniciar: summary: Iniciar com cobrança por Pix value: phone: '5511999999999' variables: nome: Maria charge: referenceId: pedido-1042 method: pix pixCode: 000201... pixKey: '39580525000189' pixKeyType: CNPJ merchantName: Loja Exemplo amountCents: 5990 description: Plano mensal pagamento: summary: Avisar que pagou value: referenceId: pedido-1042 status: paid responses: '200': description: Pagamento atualizado content: application/json: schema: $ref: '#/components/schemas/HookPaymentUpdated' example: referenceId: pedido-1042 status: paid cardUpdated: true runResumed: true '202': description: Execução iniciada content: application/json: schema: $ref: '#/components/schemas/HookStarted' example: runId: 7c1d2e90-4b3a-4c8e-9f21-5a6b7c8d9e01 status: started '400': description: '`HOOK_PAYLOAD_INVALID`, `INVALID_CHARGE` ou `INVALID_CHARGE_STATUS`.' content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: >- `HOOK_SIGNATURE_INVALID`: assinatura ausente ou errada com a assinatura ligada. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- `HOOK_SETTLEMENT_SIGNATURE_REQUIRED`: a baixa de pagamento exige a assinatura ligada. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- `HOOK_NOT_FOUND` (token inexistente ou trocado) ou `CHARGE_NOT_FOUND`. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- `AUTOMATION_INACTIVE` (automação desligada), `CHARGE_AMOUNT_MISMATCH` ou `CHARGE_ALREADY_SETTLED`. content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: '`HOOK_PAYLOAD_TOO_LARGE`: corpo acima de 64 KB.' content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Limite de chamadas do link. Respeite `Retry-After`. headers: Retry-After: schema: type: integer description: Segundos a aguardar antes de tentar de novo. content: application/json: schema: $ref: '#/components/schemas/Error' security: [] components: schemas: HookStartRequest: type: object required: - phone title: Iniciar execução properties: phone: type: string description: Telefone do cliente, com DDI. example: '5511999999999' variables: type: object nullable: true additionalProperties: type: string description: Variáveis da execução, usadas como `{{nome}}` nos passos. charge: type: object nullable: true additionalProperties: true description: > Cobrança que o passo de cobrança da automação vai enviar. `referenceId` é o seu número da cobrança: é com ele que você avisa o pagamento depois. Campos em [Link da automação e pagamento](/automacoes-webhook). HookPaymentUpdateRequest: type: object required: - referenceId - status title: Atualizar pagamento properties: referenceId: type: string description: O mesmo `charge.referenceId` enviado ao iniciar. status: type: string description: 'Novo estado da cobrança, ex.: `paid`.' example: paid HookPaymentUpdated: type: object required: - referenceId - status - cardUpdated - runResumed properties: referenceId: type: string status: type: string cardUpdated: type: boolean description: >- `true` quando a janela de 24h permitiu atualizar o cartão no WhatsApp. runResumed: type: boolean description: '`true` quando havia uma execução esperando esse pagamento.' HookStarted: type: object required: - status properties: runId: type: string format: uuid nullable: true status: type: string example: started Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string example: INSUFFICIENT_FUNDS description: >- Código estável do erro. Use este campo no seu tratamento, não a mensagem. message: type: string nullable: true description: Descrição legível, em português. Pode mudar. details: type: object additionalProperties: true description: Dados extras do erro. Vazio na maioria dos casos. example: error: code: INSUFFICIENT_FUNDS message: Saldo insuficiente. details: {} securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: ara_live_... description: >- Chave de API da Arara (`ara_live_...`), enviada no header `Authorization: Bearer ara_live_...`. Crie e gerencie as chaves no painel: https://app.ararahq.com/dashboard/apikeys. O valor completo aparece uma única vez, na criação. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.