Pular para o conteúdo

Para desenvolvedores

API e webhooks do Atendux

Ligue o Atendux ao seu ERP, ao CRM ou ao n8n: leia e mude contatos e conversas pela API e receba cada mensagem nova num webhook assinado.

  • 22 rotas REST
  • 11 eventos de webhook
  • OpenAPI 3.1
  • Em todos os planos
Webhook recebido
POST /webhooks/atendux HTTP/1.1
X-Atendux-Event: message.received
X-Atendux-Signature: t=1793975530,v1=692f6b06e676…

{
  "type": "message.received",
  "data": {
    "message": {
      "direction": "in",
      "type": "text",
      "text": "Olá! Meu pedido já saiu para entrega?"
    }
  }
}
Nesta página
  1. Visão geral
  2. Autenticação e escopos
  3. Limites
  4. Erros
  5. Receber webhooks
  6. Eventos
  7. Rotas
  8. Contatos
  9. Conversas
  10. Consultas
  11. Webhooks pela API

Visão geral

A API é para o sistema da sua empresa conversar com o Atendux sem ninguém copiar e colar. Está em todos os planos e usa JSON, chaves com escopo e erros num formato só.

  • ERP e loja virtual. Crie o contato quando o pedido entra e mande o modelo “pedido enviado” pelo WhatsApp oficial.
  • CRM. Receba um webhook quando chega mensagem, quando a conversa é encerrada ou quando o cliente responde a pesquisa.
  • n8n, Make e Zapier. Use o passo de pedido HTTP com a chave no cabeçalho e o gatilho de webhook com o endereço que a ferramenta dá.
Endereço base
https://api.atendux.tech/public/v1
Especificação
openapi.json, OpenAPI 3.1, sem autenticação. Importe no Postman, no Insomnia ou no gerador de cliente que preferir.
Listas
Paginam por cursor: limit até 100 e nextCursor para a próxima página (null no fim).
Formatos
Datas em ISO 8601 (UTC). Telefones só com dígitos, com o código do país (5548999990000).
Primeiro pedido
curl "https://api.atendux.tech/public/v1/contacts?limit=1" \
  -H "Authorization: Bearer $ATENDUX_API_KEY"

Autenticação e escopos

  1. No Atendux, abra Configurações → Integrações → API e webhooks. A aba aparece para quem administra as integrações da empresa.
  2. Clique em Criar chave, dê um nome (por exemplo, “ERP da loja”), marque só os escopos de que o sistema precisa e escolha a validade: 30, 90 ou 365 dias, ou sem validade.
  3. Copie a chave. Ela começa com atx_ e aparece uma vez só: o Atendux guarda apenas uma impressão dela.
Cabeçalho de todo pedido
Authorization: Bearer atx_...

A chave age em nome de quem a criou, com as permissões que essa pessoa tem no painel, limitadas aos escopos marcados. Mensagens enviadas pela API aparecem como dela. Se a pessoa sair da empresa, a chave para de funcionar. Revogar corta o acesso no pedido seguinte.

Escopos

Contatos

Conversas

Mensagens

Consultas

  • tags:readVer etiquetas

    Lista as etiquetas da empresa.

    GET/tags

  • queues:readVer setores

    Lista os setores e quem atende em cada um.

    GET/queues

  • channels:readVer canais

    Lista os canais conectados, sem as credenciais.

    GET/channels

Webhooks

Limites

O limite é por empresa e por minuto, somando todas as chaves. Conta sem plano conhecido fica com o menor, 60 pedidos.

Pedidos por minuto em cada plano
PlanoPedidos por minuto
Light60
Essencial120
Equipe300
Empresa600

Toda resposta traz X-RateLimit-Limit e X-RateLimit-Remaining. Acima do limite, a resposta é 429 RATE_LIMITED com Retry-After em segundos.

Resposta acima do limite
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Limite de pedidos por minuto atingido."
  }
}

Erros

Todo erro tem o mesmo formato. Trate pelo code, que não muda; a message é em português e pode mudar de texto.

Corpo de erro (exemplo)
{
  "error": {
    "code": "FORBIDDEN_SCOPE",
    "message": "Esta chave não tem acesso a esta rota.",
    "details": {
      "scope": "contacts:write"
    }
  }
}
  • 400INVALID_PAYLOAD

    Corpo ou consulta inválidos. details.field diz o campo.

  • 401UNAUTHENTICATED

    Sem chave, chave inválida, revogada ou vencida.

  • 403FORBIDDEN_SCOPE

    A chave não tem o escopo da rota. details.scope diz qual falta.

  • 403FORBIDDEN_PERMISSION

    Quem criou a chave não tem a permissão no painel para fazer isso.

  • 403SUBSCRIPTION_INACTIVE

    A assinatura da empresa não está ativa.

  • 403TERMS_NOT_ACCEPTED

    Quem criou a chave ainda não aceitou os termos novos.

  • 404NOT_FOUND

    Não existe, ou é de outra empresa.

  • 409CONFLICT

    A mudança não cabe no estado atual do registro.

  • 409CONTACT_EXISTS

    Já há um contato com o telefone ou o e-mail. details.contactId traz o existente.

  • 409CONVERSATION_CLOSED

    A conversa está encerrada.

  • 409CONVERSATION_NOT_YOURS

    A conversa está com outra pessoa.

  • 409WINDOW_CLOSED

    Passaram 24 horas da última mensagem do cliente no WhatsApp oficial: só modelo aprovado.

  • 409WEBHOOK_LIMIT

    A empresa já tem 10 webhooks.

  • 429RATE_LIMITED

    Passou do limite por minuto. Espere os segundos do Retry-After.

Receber webhooks

Um webhook é um endereço do seu sistema que o Atendux chama quando algo acontece. Crie em Configurações → Integrações → API e webhooks ou pela rota POST /webhooks, com até 10 por empresa. O endereço precisa ser https:// e de um sistema da sua empresa ou de um fornecedor contratado por ela. Na criação, o Atendux mostra uma vez o segredo whsec_..., que assina cada envio.

O que chega

Um POST com o evento em JSON, nos campos id, type, createdAt, organizationId e data. O texto das mensagens e o telefone, o nome e o e-mail dos clientes só vão se a empresa marcar essas caixas no webhook; sem elas, esses campos chegam null.

  • Content-Type

    application/json

  • User-Agent

    Atendux-Webhooks/1.0

  • X-Atendux-Event

    O tipo do evento, igual ao campo type.

  • X-Atendux-Delivery

    Id desta entrega. Muda a cada reenvio; o id do evento, não.

  • X-Atendux-Signature

    t=<unix>,v1=<hex>: v1 é o HMAC-SHA256, em hexadecimal, de "<t>.<corpo>" com o segredo do webhook.

Envio de exemplo
POST /webhooks/atendux HTTP/1.1
Host: erp.suaempresa.com.br
Content-Type: application/json
User-Agent: Atendux-Webhooks/1.0
X-Atendux-Event: message.received
X-Atendux-Delivery: 98ad81f6-be04-41da-8c82-0983ae0a8231
X-Atendux-Signature: t=1793975530,v1=692f6b06e67646fbd73d8a9333270fb343519e6e4b4d3651bd82542afc26e46a

{
  "id": "f09e910f-8cbd-4aa2-9819-b324873d0f69",
  "type": "message.received",
  "createdAt": "2026-11-06T14:32:10.000Z",
  "organizationId": "74932688-59d5-4638-8717-7281dfe82765",
  "data": {
    "message": {
      "id": "0b1ad1d8-5d95-418e-8cae-08e1aa8a352d",
      "conversationId": "c2972b33-4bb9-419a-926d-27c22b3f8a9d",
      "direction": "in",
      "sender": "contact",
      "authorName": "Maria Souza",
      "type": "text",
      "text": "Olá! Meu pedido já saiu para entrega?",
      "media": null,
      "status": "pending",
      "error": null,
      "templateName": null,
      "createdAt": "2026-11-06T14:32:10.000Z"
    },
    "conversation": {
      "id": "c9b7df5e-9a28-47d0-921f-068306ecf451",
      "contactId": "8caad7f2-86b4-4736-a48e-6d0f8ea575f5",
      "channelId": "5de60e3d-48e9-4372-94db-5fd8d2fd4d41"
    }
  }
}

Esse envio foi assinado de verdade com o segredo de exemplo whsec_7Hq2mZ9xKp4vT1sLc8NwR3bYdF6gJ0eA5uQiVoXkE2r: use-o para testar a sua verificação.

Conferir a assinatura

Calcule o HMAC-SHA256 de <t>.<corpo cru> com o segredo, compare com o v1 em tempo constante e recuse t com mais de 5 minutos, para ninguém reaproveitar um envio antigo.

Exemplo em Node (Express)
import crypto from 'node:crypto'
import express from 'express'

const SECRET = process.env.ATENDUX_WEBHOOK_SECRET // whsec_...
const TOLERANCE_S = 5 * 60 // recusa assinatura com mais de 5 minutos

function isValid(header, rawBody) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
  const t = Number(parts.t)
  if (!t || Math.abs(Date.now() / 1000 - t) > TOLERANCE_S) return false
  const expected = crypto
    .createHmac('sha256', SECRET)
    .update(`${t}.${rawBody}`)
    .digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(parts.v1 ?? '')
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

const app = express()
const seen = new Set() // em produção, guarde os ids no seu banco

// express.raw: a assinatura vale para o corpo cru, antes do JSON.parse
app.post('/webhooks/atendux', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8')
  if (!isValid(req.get('X-Atendux-Signature') ?? '', rawBody)) return res.sendStatus(401)

  const event = JSON.parse(rawBody)
  res.sendStatus(200) // responda logo e processe depois

  if (seen.has(event.id)) return // reenvio: o id do evento é o mesmo
  seen.add(event.id)
  console.log(event.type, event.data)
})

app.listen(8080)

Responder e novas tentativas

Responda com qualquer 2xx em até 10 segundos; processe o resto depois. Não seguimos redirecionamento. Sem 2xx, o Atendux tenta de novo, até 7 vezes no total:

  1. 1ªna hora
  2. 2ª+1 min1 min depois
  3. 3ª+5 min6 min depois
  4. 4ª+30 min36 min depois
  5. 5ª+2 h2 h 36 min depois
  6. 6ª+6 h8 h 36 min depois
  7. 7ª+12 h20 h 36 min depois
  • A última tentativa sai cerca de 20 h 36 min depois da primeira. Depois dela, a entrega fica como “Falhou”, e dá para reenviar pela tela.
  • O mesmo evento pode chegar mais de uma vez (nova tentativa ou reenvio). Descarte repetidos pelo id do evento, que não muda.
  • Um webhook que passa 3 dias falhando, sem nenhuma entrega certa, é desligado sozinho, e o dono da empresa recebe um e-mail. Ligar de novo zera a contagem.
  • O registro de cada entrega fica 30 dias na tela; o corpo, 7 dias (depois disso não dá para reenviar).

Eventos

Escolha os eventos de cada webhook. O data de cada um está abaixo, com um exemplo completo (as caixas de conteúdo e de dados de contato marcadas).

Mensagens

Mensagem recebidamessage.receivedO cliente mandou uma mensagem.
Corpo de message.received
{
  "id": "f09e910f-8cbd-4aa2-9819-b324873d0f69",
  "type": "message.received",
  "createdAt": "2026-11-06T14:32:10.000Z",
  "organizationId": "74932688-59d5-4638-8717-7281dfe82765",
  "data": {
    "message": {
      "id": "0b1ad1d8-5d95-418e-8cae-08e1aa8a352d",
      "conversationId": "c2972b33-4bb9-419a-926d-27c22b3f8a9d",
      "direction": "in",
      "sender": "contact",
      "authorName": "Maria Souza",
      "type": "text",
      "text": "Olá! Meu pedido já saiu para entrega?",
      "media": null,
      "status": "pending",
      "error": null,
      "templateName": null,
      "createdAt": "2026-11-06T14:32:10.000Z"
    },
    "conversation": {
      "id": "c9b7df5e-9a28-47d0-921f-068306ecf451",
      "contactId": "8caad7f2-86b4-4736-a48e-6d0f8ea575f5",
      "channelId": "5de60e3d-48e9-4372-94db-5fd8d2fd4d41"
    }
  }
}
Mensagem enviadamessage.sentUma mensagem da empresa saiu pelo canal (equipe, fluxo, automação ou o celular conectado).
Corpo de message.sent
{
  "id": "f09e910f-8cbd-4aa2-9819-b324873d0f69",
  "type": "message.sent",
  "createdAt": "2026-11-06T14:32:10.000Z",
  "organizationId": "74932688-59d5-4638-8717-7281dfe82765",
  "data": {
    "message": {
      "id": "0b1ad1d8-5d95-418e-8cae-08e1aa8a352d",
      "conversationId": "c2972b33-4bb9-419a-926d-27c22b3f8a9d",
      "direction": "out",
      "sender": "agent",
      "authorName": "Ana Lima",
      "type": "text",
      "text": "Saiu hoje! Chega até sexta.",
      "media": null,
      "status": "sent",
      "error": null,
      "templateName": null,
      "createdAt": "2026-11-06T14:32:10.000Z"
    },
    "conversation": {
      "id": "c9b7df5e-9a28-47d0-921f-068306ecf451",
      "contactId": "8caad7f2-86b4-4736-a48e-6d0f8ea575f5",
      "channelId": "5de60e3d-48e9-4372-94db-5fd8d2fd4d41"
    }
  }
}
Situação da mensagemmessage.status_updatedUma mensagem enviada foi entregue, lida ou falhou.
Corpo de message.status_updated
{
  "id": "f09e910f-8cbd-4aa2-9819-b324873d0f69",
  "type": "message.status_updated",
  "createdAt": "2026-11-06T14:32:10.000Z",
  "organizationId": "74932688-59d5-4638-8717-7281dfe82765",
  "data": {
    "message": {
      "id": "0b1ad1d8-5d95-418e-8cae-08e1aa8a352d",
      "conversationId": "c2972b33-4bb9-419a-926d-27c22b3f8a9d",
      "direction": "out",
      "sender": "agent",
      "authorName": "Ana Lima",
      "type": "text",
      "text": "Saiu hoje! Chega até sexta.",
      "media": null,
      "status": "read",
      "error": null,
      "templateName": null,
      "createdAt": "2026-11-06T14:32:10.000Z"
    },
    "conversation": {
      "id": "c9b7df5e-9a28-47d0-921f-068306ecf451",
      "contactId": "8caad7f2-86b4-4736-a48e-6d0f8ea575f5",
      "channelId": "5de60e3d-48e9-4372-94db-5fd8d2fd4d41"
    }
  }
}

Conversas

Conversa novaconversation.createdUma conversa começou (o cliente escreveu ou a empresa iniciou).
Corpo de conversation.created
{
  "id": "f09e910f-8cbd-4aa2-9819-b324873d0f69",
  "type": "conversation.created",
  "createdAt": "2026-11-06T14:32:10.000Z",
  "organizationId": "74932688-59d5-4638-8717-7281dfe82765",
  "data": {
    "conversation": {
      "id": "c9b7df5e-9a28-47d0-921f-068306ecf451",
      "status": "open",
      "contact": {
        "id": "db0f7138-314f-44b0-96a5-77b14bf12705",
        "name": "Maria Souza",
        "phone": "5548999990000",
        "email": "[email protected]"
      },
      "channel": {
        "id": "fcd32149-dd0d-4e92-a078-e85a9c069fe5",
        "type": "whatsapp_cloud",
        "name": "WhatsApp da loja"
      },
      "queue": {
        "id": "e4231cb5-cfca-47d2-921a-6a7650e68b45",
        "name": "Vendas"
      },
      "assignee": null,
      "tags": [
        {
          "id": "ffad4e74-957e-4ea8-b527-7915092eee1d",
          "name": "Cliente VIP",
          "color": "teal"
        }
      ],
      "unreadCount": 1,
      "lastMessageAt": "2026-11-06T14:32:10.000Z",
      "lastInboundAt": "2026-11-06T14:32:10.000Z",
      "createdAt": "2026-11-06T14:32:10.000Z",
      "closedAt": null
    },
    "previous": {
      "assigneeId": "32629deb-59b3-431a-8e53-2d9c458109e9",
      "queueId": "bc7c2153-1b4e-4e6e-b697-adea89812ac9"
    }
  }
}
Conversa atribuídaconversation.assignedUma conversa sem responsável ganhou um.
Corpo de conversation.assigned
{
  "id": "f09e910f-8cbd-4aa2-9819-b324873d0f69",
  "type": "conversation.assigned",
  "createdAt": "2026-11-06T14:32:10.000Z",
  "organizationId": "74932688-59d5-4638-8717-7281dfe82765",
  "data": {
    "conversation": {
      "id": "c9b7df5e-9a28-47d0-921f-068306ecf451",
      "status": "open",
      "contact": {
        "id": "db0f7138-314f-44b0-96a5-77b14bf12705",
        "name": "Maria Souza",
        "phone": "5548999990000",
        "email": "[email protected]"
      },
      "channel": {
        "id": "fcd32149-dd0d-4e92-a078-e85a9c069fe5",
        "type": "whatsapp_cloud",
        "name": "WhatsApp da loja"
      },
      "queue": {
        "id": "e4231cb5-cfca-47d2-921a-6a7650e68b45",
        "name": "Vendas"
      },
      "assignee": {
        "id": "5b5c6839-239d-4c6a-ac65-0b7025c6c349",
        "name": "Ana Lima"
      },
      "tags": [
        {
          "id": "ffad4e74-957e-4ea8-b527-7915092eee1d",
          "name": "Cliente VIP",
          "color": "teal"
        }
      ],
      "unreadCount": 2,
      "lastMessageAt": "2026-11-06T14:32:10.000Z",
      "lastInboundAt": "2026-11-06T14:32:10.000Z",
      "createdAt": "2026-11-06T14:32:10.000Z",
      "closedAt": null
    },
    "previous": {
      "assigneeId": null,
      "queueId": "bc7c2153-1b4e-4e6e-b697-adea89812ac9"
    }
  }
}
Conversa transferidaconversation.transferredA conversa mudou de pessoa ou de setor.
Corpo de conversation.transferred
{
  "id": "f09e910f-8cbd-4aa2-9819-b324873d0f69",
  "type": "conversation.transferred",
  "createdAt": "2026-11-06T14:32:10.000Z",
  "organizationId": "74932688-59d5-4638-8717-7281dfe82765",
  "data": {
    "conversation": {
      "id": "c9b7df5e-9a28-47d0-921f-068306ecf451",
      "status": "open",
      "contact": {
        "id": "db0f7138-314f-44b0-96a5-77b14bf12705",
        "name": "Maria Souza",
        "phone": "5548999990000",
        "email": "[email protected]"
      },
      "channel": {
        "id": "fcd32149-dd0d-4e92-a078-e85a9c069fe5",
        "type": "whatsapp_cloud",
        "name": "WhatsApp da loja"
      },
      "queue": {
        "id": "e4231cb5-cfca-47d2-921a-6a7650e68b45",
        "name": "Vendas"
      },
      "assignee": {
        "id": "5b5c6839-239d-4c6a-ac65-0b7025c6c349",
        "name": "Ana Lima"
      },
      "tags": [
        {
          "id": "ffad4e74-957e-4ea8-b527-7915092eee1d",
          "name": "Cliente VIP",
          "color": "teal"
        }
      ],
      "unreadCount": 2,
      "lastMessageAt": "2026-11-06T14:32:10.000Z",
      "lastInboundAt": "2026-11-06T14:32:10.000Z",
      "createdAt": "2026-11-06T14:32:10.000Z",
      "closedAt": null
    },
    "previous": {
      "assigneeId": "32629deb-59b3-431a-8e53-2d9c458109e9",
      "queueId": "bc7c2153-1b4e-4e6e-b697-adea89812ac9"
    }
  }
}
Conversa encerradaconversation.closedA conversa foi encerrada pela equipe, por um fluxo ou por inatividade.
Corpo de conversation.closed
{
  "id": "f09e910f-8cbd-4aa2-9819-b324873d0f69",
  "type": "conversation.closed",
  "createdAt": "2026-11-06T14:32:10.000Z",
  "organizationId": "74932688-59d5-4638-8717-7281dfe82765",
  "data": {
    "conversation": {
      "id": "c9b7df5e-9a28-47d0-921f-068306ecf451",
      "status": "closed",
      "contact": {
        "id": "db0f7138-314f-44b0-96a5-77b14bf12705",
        "name": "Maria Souza",
        "phone": "5548999990000",
        "email": "[email protected]"
      },
      "channel": {
        "id": "fcd32149-dd0d-4e92-a078-e85a9c069fe5",
        "type": "whatsapp_cloud",
        "name": "WhatsApp da loja"
      },
      "queue": {
        "id": "e4231cb5-cfca-47d2-921a-6a7650e68b45",
        "name": "Vendas"
      },
      "assignee": {
        "id": "5b5c6839-239d-4c6a-ac65-0b7025c6c349",
        "name": "Ana Lima"
      },
      "tags": [
        {
          "id": "ffad4e74-957e-4ea8-b527-7915092eee1d",
          "name": "Cliente VIP",
          "color": "teal"
        }
      ],
      "unreadCount": 0,
      "lastMessageAt": "2026-11-06T14:32:10.000Z",
      "lastInboundAt": "2026-11-06T14:32:10.000Z",
      "createdAt": "2026-11-06T14:32:10.000Z",
      "closedAt": "2026-11-06T14:32:10.000Z"
    },
    "previous": {
      "assigneeId": "32629deb-59b3-431a-8e53-2d9c458109e9",
      "queueId": "bc7c2153-1b4e-4e6e-b697-adea89812ac9"
    }
  }
}
Conversa reabertaconversation.reopenedUma conversa encerrada foi reaberta.
Corpo de conversation.reopened
{
  "id": "f09e910f-8cbd-4aa2-9819-b324873d0f69",
  "type": "conversation.reopened",
  "createdAt": "2026-11-06T14:32:10.000Z",
  "organizationId": "74932688-59d5-4638-8717-7281dfe82765",
  "data": {
    "conversation": {
      "id": "c9b7df5e-9a28-47d0-921f-068306ecf451",
      "status": "open",
      "contact": {
        "id": "db0f7138-314f-44b0-96a5-77b14bf12705",
        "name": "Maria Souza",
        "phone": "5548999990000",
        "email": "[email protected]"
      },
      "channel": {
        "id": "fcd32149-dd0d-4e92-a078-e85a9c069fe5",
        "type": "whatsapp_cloud",
        "name": "WhatsApp da loja"
      },
      "queue": {
        "id": "e4231cb5-cfca-47d2-921a-6a7650e68b45",
        "name": "Vendas"
      },
      "assignee": {
        "id": "5b5c6839-239d-4c6a-ac65-0b7025c6c349",
        "name": "Ana Lima"
      },
      "tags": [
        {
          "id": "ffad4e74-957e-4ea8-b527-7915092eee1d",
          "name": "Cliente VIP",
          "color": "teal"
        }
      ],
      "unreadCount": 2,
      "lastMessageAt": "2026-11-06T14:32:10.000Z",
      "lastInboundAt": "2026-11-06T14:32:10.000Z",
      "createdAt": "2026-11-06T14:32:10.000Z",
      "closedAt": null
    },
    "previous": {
      "assigneeId": "32629deb-59b3-431a-8e53-2d9c458109e9",
      "queueId": "bc7c2153-1b4e-4e6e-b697-adea89812ac9"
    }
  }
}

Contatos

Contato novocontact.createdUm contato foi criado (pela equipe, pela API ou na primeira mensagem). Não sai para importação em lote.
Corpo de contact.created
{
  "id": "f09e910f-8cbd-4aa2-9819-b324873d0f69",
  "type": "contact.created",
  "createdAt": "2026-11-06T14:32:10.000Z",
  "organizationId": "74932688-59d5-4638-8717-7281dfe82765",
  "data": {
    "contact": {
      "id": "09396409-6401-499a-9500-5d98db022885",
      "name": "Maria Souza",
      "phone": "5548999990000",
      "email": "[email protected]",
      "company": "Loja Exemplo",
      "notes": "Prefere contato à tarde.",
      "customFields": {
        "pedido": "1234"
      },
      "origin": "channel",
      "tags": [
        {
          "id": "8f768277-4f97-4ba6-86f9-37569091f619",
          "name": "Cliente VIP",
          "color": "teal"
        }
      ],
      "createdAt": "2026-11-06T14:32:10.000Z"
    }
  }
}
Contato alteradocontact.updatedOs dados ou as etiquetas de um contato mudaram.
Corpo de contact.updated
{
  "id": "f09e910f-8cbd-4aa2-9819-b324873d0f69",
  "type": "contact.updated",
  "createdAt": "2026-11-06T14:32:10.000Z",
  "organizationId": "74932688-59d5-4638-8717-7281dfe82765",
  "data": {
    "contact": {
      "id": "09396409-6401-499a-9500-5d98db022885",
      "name": "Maria Souza",
      "phone": "5548999990000",
      "email": "[email protected]",
      "company": "Loja Exemplo",
      "notes": "Prefere contato à tarde.",
      "customFields": {
        "pedido": "1234"
      },
      "origin": "channel",
      "tags": [
        {
          "id": "8f768277-4f97-4ba6-86f9-37569091f619",
          "name": "Cliente VIP",
          "color": "teal"
        }
      ],
      "createdAt": "2026-11-06T14:32:10.000Z"
    }
  }
}

Pesquisas

Pesquisa respondidasurvey.answeredO cliente deu a nota de uma pesquisa. Sai de novo, com o mesmo id da resposta, quando ele manda o comentário.
Corpo de survey.answered
{
  "id": "f09e910f-8cbd-4aa2-9819-b324873d0f69",
  "type": "survey.answered",
  "createdAt": "2026-11-06T14:32:10.000Z",
  "organizationId": "74932688-59d5-4638-8717-7281dfe82765",
  "data": {
    "answer": {
      "id": "c91a197d-b2f9-48c2-acd3-de9a0067bc65",
      "surveyId": "36bffb07-34ce-4ca6-b15d-c9f8686ba309",
      "surveyName": "Satisfação do atendimento",
      "kind": "csat",
      "score": 5,
      "label": "Muito satisfeito",
      "comment": "Atendimento rápido, obrigado!",
      "answeredAt": "2026-11-06T14:32:10.000Z"
    },
    "conversationId": "6ff416c0-5d27-443a-8c5b-56215d2d5215",
    "contactId": "45e2067d-7642-43c2-8faa-174ee0f95add"
  }
}

Rotas

Todas debaixo de https://api.atendux.tech/public/v1, com a chave no cabeçalho. Cada rota pede um escopo; a permissão de quem criou a chave também vale.

Contatos

Listar e buscar contatos

GET/contacts

Contatos da empresa, dos mais recentes para os mais antigos, com busca por nome, e-mail ou telefone.

Escopo contacts:read (Ver contatos)

  • qconsulta

    texto, até 80

    Busca por nome, e-mail ou telefone (2 caracteres ou mais).

  • cursorconsulta

    texto, até 512

    Cursor da próxima página.

  • limitconsulta

    inteiro, 1 a 100

    Itens por página (1 a 100, padrão 50).

Pedido em curl
curl "https://api.atendux.tech/public/v1/contacts?q=maria" \
  -H "Authorization: Bearer $ATENDUX_API_KEY"
Resposta 200
Resposta 200
{
  "contacts": [
    {
      "id": "6916b609-cf3a-40b2-9bf0-ca96819f66d5",
      "name": "Maria Souza",
      "phone": "5548999990000",
      "email": "[email protected]",
      "company": "Loja Exemplo",
      "notes": "Prefere contato à tarde.",
      "customFields": {
        "pedido": "1234"
      },
      "origin": "channel",
      "tags": [
        {
          "id": "5dc36477-8c51-4b96-b384-1c94058529d9",
          "name": "Cliente VIP",
          "color": "teal"
        }
      ],
      "createdAt": "2026-11-06T14:32:10.000Z"
    }
  ],
  "nextCursor": null
}

Criar contato

POST/contacts

Cria um contato com nome, telefone ou e-mail. Telefone ou e-mail já cadastrado responde 409 CONTACT_EXISTS (details.contactId traz o existente).

Escopo contacts:write (Criar e editar contatos)

  • namecorpo

    texto, até 1.000 ou null

  • phonecorpo

    texto, até 40 ou null

  • emailcorpo

    texto, até 1.000 ou null

  • notescorpo

    texto, até 20.000 ou null

  • tagIdscorpo

    lista de uuid, até 50

Pedido em curl
curl -X POST "https://api.atendux.tech/public/v1/contacts" \
  -H "Authorization: Bearer $ATENDUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Maria Souza",
  "phone": "5548999990000",
  "email": "[email protected]",
  "notes": "Prefere contato à tarde.",
  "tagIds": [
    "4e406042-82f6-4f3a-8914-009f21854929"
  ]
}'
Resposta 201
Resposta 201
{
  "id": "5c5a1db7-5bd5-4bf2-ac2e-4a20a6397ec9",
  "name": "Maria Souza",
  "phone": "5548999990000",
  "email": "[email protected]",
  "company": "Loja Exemplo",
  "notes": "Prefere contato à tarde.",
  "customFields": {
    "pedido": "1234"
  },
  "origin": "channel",
  "tags": [
    {
      "id": "cc64c03d-4bf5-45d2-a2a9-6f629798d885",
      "name": "Cliente VIP",
      "color": "teal"
    }
  ],
  "createdAt": "2026-11-06T14:32:10.000Z"
}

Ver contato

GET/contacts/{id}

Um contato, com telefone, e-mail, campos personalizados e etiquetas.

Escopo contacts:read (Ver contatos)

  • idcaminhoobrigatório

    uuid

    Id do contato.

Pedido em curl
curl "https://api.atendux.tech/public/v1/contacts/17e020f6-dd06-4a14-8e5b-f07f32ded271" \
  -H "Authorization: Bearer $ATENDUX_API_KEY"
Resposta 200
Resposta 200
{
  "id": "6d1c8fad-9579-4d42-b612-f558d9363c09",
  "name": "Maria Souza",
  "phone": "5548999990000",
  "email": "[email protected]",
  "company": "Loja Exemplo",
  "notes": "Prefere contato à tarde.",
  "customFields": {
    "pedido": "1234"
  },
  "origin": "channel",
  "tags": [
    {
      "id": "657e026b-cf01-49a2-a727-721ab7b5b265",
      "name": "Cliente VIP",
      "color": "teal"
    }
  ],
  "createdAt": "2026-11-06T14:32:10.000Z"
}

Editar contato

PATCH/contacts/{id}

Muda só os campos enviados. O telefone que veio do WhatsApp não muda (409 CONFLICT).

Escopo contacts:write (Criar e editar contatos)

  • idcaminhoobrigatório

    uuid

    Id do contato.

  • namecorpo

    texto, até 120

  • emailcorpo

    e-mail ou null

  • phonecorpo

    texto, até 40 ou null

  • companycorpo

    texto, até 120 ou null

  • notescorpo

    texto, até 2.000 ou null

  • customFieldscorpo

    objeto

Pedido em curl
curl -X PATCH "https://api.atendux.tech/public/v1/contacts/b73356e1-40f1-4072-8043-e658e9125ced" \
  -H "Authorization: Bearer $ATENDUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Maria Souza",
  "email": "[email protected]",
  "phone": "5548999990000",
  "company": "Loja Exemplo",
  "notes": "Prefere contato à tarde.",
  "customFields": {
    "pedido": "1234"
  }
}'
Resposta 200
Resposta 200
{
  "id": "d242e0c0-7ded-4c60-b218-5e3979055715",
  "name": "Maria Souza",
  "phone": "5548999990000",
  "email": "[email protected]",
  "company": "Loja Exemplo",
  "notes": "Prefere contato à tarde.",
  "customFields": {
    "pedido": "1234"
  },
  "origin": "channel",
  "tags": [
    {
      "id": "ac3ad6ce-50db-4938-9160-8f6b0c49a261",
      "name": "Cliente VIP",
      "color": "teal"
    }
  ],
  "createdAt": "2026-11-06T14:32:10.000Z"
}

Trocar as etiquetas do contato

PUT/contacts/{id}/tags

O contato fica exatamente com as etiquetas enviadas.

Escopo contacts:write (Criar e editar contatos)

  • idcaminhoobrigatório

    uuid

    Id do contato.

  • tagIdscorpoobrigatório

    lista de uuid, até 100

    Ids das etiquetas (GET /tags). Lista vazia tira todas.

Pedido em curl
curl -X PUT "https://api.atendux.tech/public/v1/contacts/2293ff11-65f1-4f12-bf49-a7f4023ec895/tags" \
  -H "Authorization: Bearer $ATENDUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tagIds": [
    "056d2edb-6010-4192-98a4-8eea5be82935"
  ]
}'
Resposta 200
Resposta 200
{
  "id": "02d9e494-339b-4cc4-aa81-442dd69e07a5",
  "name": "Cliente VIP",
  "phone": "5548999990000",
  "email": "[email protected]",
  "company": "Loja Exemplo",
  "notes": "Prefere contato à tarde.",
  "customFields": {
    "pedido": "1234"
  },
  "origin": "channel",
  "tags": [
    {
      "id": "7b52fbf2-2289-4454-b807-6a7712ab4541",
      "name": "Cliente VIP",
      "color": "teal"
    }
  ],
  "createdAt": "2026-11-06T14:32:10.000Z"
}

Conversas

Listar conversas

GET/conversations

Conversas da empresa, das mais novas para as mais antigas, com filtro de situação, setor e atividade desde uma data.

Escopo conversations:read (Ver conversas)

  • statusconsulta

    open | closed

    open ou closed. Sem ele, as duas.

  • queueIdconsulta

    uuid

    Só as conversas deste setor.

  • updatedSinceconsulta

    data e hora ISO 8601

    Só as conversas com atividade a partir desta data (ISO 8601).

  • cursorconsulta

    texto, até 512

    Cursor da próxima página.

  • limitconsulta

    inteiro, 1 a 100

    Itens por página (1 a 100, padrão 50).

Pedido em curl
curl "https://api.atendux.tech/public/v1/conversations?status=open" \
  -H "Authorization: Bearer $ATENDUX_API_KEY"
Resposta 200
Resposta 200
{
  "conversations": [
    {
      "id": "1371db0f-d276-41e6-882c-87e851e000a1",
      "status": "open",
      "contact": {
        "id": "2568c6ad-059c-41a2-919e-837a64a31ce5",
        "name": "Maria Souza",
        "phone": "5548999990000",
        "email": "[email protected]"
      },
      "channel": {
        "id": "bdbf27fc-1997-4c94-bcd2-4265d4f20855",
        "type": "whatsapp_cloud",
        "name": "WhatsApp da loja"
      },
      "queue": {
        "id": "2cf209d8-defd-4310-9e09-7881aaa4080d",
        "name": "Vendas"
      },
      "assignee": {
        "id": "e8098ab6-288a-4e26-9f40-49233fc25525",
        "name": "Ana Lima"
      },
      "tags": [
        {
          "id": "674d9255-e618-4a12-85dd-53ee22b25e75",
          "name": "Cliente VIP",
          "color": "teal"
        }
      ],
      "unreadCount": 2,
      "lastMessageAt": "2026-11-06T14:32:10.000Z",
      "lastInboundAt": "2026-11-06T14:32:10.000Z",
      "createdAt": "2026-11-06T14:32:10.000Z",
      "closedAt": null
    }
  ],
  "nextCursor": null
}

Ver conversa

GET/conversations/{id}

A conversa, com contato, canal, setor, responsável e etiquetas.

Escopo conversations:read (Ver conversas)

  • idcaminhoobrigatório

    uuid

    Id da conversa.

Pedido em curl
curl "https://api.atendux.tech/public/v1/conversations/c8c0cb77-b846-47a2-a61a-e99639966b15" \
  -H "Authorization: Bearer $ATENDUX_API_KEY"
Resposta 200
Resposta 200
{
  "id": "6d1c8fad-9579-4d42-b612-f558d9363c09",
  "status": "open",
  "contact": {
    "id": "893b9957-375d-4bb6-a660-4db268cec041",
    "name": "Maria Souza",
    "phone": "5548999990000",
    "email": "[email protected]"
  },
  "channel": {
    "id": "5a56a2da-e033-4ebe-a6c3-bbef2e124449",
    "type": "whatsapp_cloud",
    "name": "WhatsApp da loja"
  },
  "queue": {
    "id": "af6c7282-1ca9-4682-b6cd-18ef9d7dca55",
    "name": "Vendas"
  },
  "assignee": {
    "id": "7aa5c5d4-aeab-47ec-8c28-30fd2a175445",
    "name": "Ana Lima"
  },
  "tags": [
    {
      "id": "657e026b-cf01-49a2-a727-721ab7b5b265",
      "name": "Cliente VIP",
      "color": "teal"
    }
  ],
  "unreadCount": 2,
  "lastMessageAt": "2026-11-06T14:32:10.000Z",
  "lastInboundAt": "2026-11-06T14:32:10.000Z",
  "createdAt": "2026-11-06T14:32:10.000Z",
  "closedAt": null
}

Ler mensagens

GET/conversations/{id}/messages

As mensagens mais recentes, em ordem cronológica. Para as mais antigas, passe o nextCursor em before.

Escopo conversations:read (Ver conversas)

  • idcaminhoobrigatório

    uuid

    Id da conversa.

  • beforeconsulta

    texto, até 512

    Cursor (nextCursor) para buscar mensagens mais antigas.

  • limitconsulta

    inteiro, 1 a 100

    Itens por página (1 a 100, padrão 50).

Pedido em curl
curl "https://api.atendux.tech/public/v1/conversations/0a221d09-1470-4852-a0b9-86d63b0be8e5/messages" \
  -H "Authorization: Bearer $ATENDUX_API_KEY"
Resposta 200
Resposta 200
{
  "messages": [
    {
      "id": "49c5db67-782a-43fa-8588-6a1c5481c821",
      "conversationId": "37e94fcc-4040-4ac0-973d-a46dbe5fa93d",
      "direction": "in",
      "sender": "contact",
      "authorName": "Maria Souza",
      "type": "text",
      "text": "Olá! Meu pedido já saiu para entrega?",
      "media": null,
      "status": "pending",
      "error": null,
      "templateName": null,
      "createdAt": "2026-11-06T14:32:10.000Z"
    }
  ],
  "nextCursor": null
}

Enviar texto

POST/conversations/{id}/messages

Responde a conversa como a pessoa que criou a chave. Conversa encerrada (409 CONVERSATION_CLOSED), com outra pessoa (409 CONVERSATION_NOT_YOURS) ou com a janela de 24 horas da Cloud API fechada (409 WINDOW_CLOSED) não recebe.

Escopo messages:send (Enviar mensagens)

  • idcaminhoobrigatório

    uuid

    Id da conversa.

  • textcorpoobrigatório

    texto, até 4.096

  • subjectcorpo

    texto, até 200

Pedido em curl
curl -X POST "https://api.atendux.tech/public/v1/conversations/003b874f-7d0c-47c2-b9a3-2130385577d1/messages" \
  -H "Authorization: Bearer $ATENDUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Olá! Meu pedido já saiu para entrega?",
  "subject": "texto"
}'
Resposta 201
Resposta 201
{
  "id": "f8416e55-9b4d-49f2-9813-2c7acd270315",
  "conversationId": "5a7234e2-649a-4f14-ba6e-8d1774b52259",
  "direction": "in",
  "sender": "contact",
  "authorName": "Maria Souza",
  "type": "text",
  "text": "Olá! Meu pedido já saiu para entrega?",
  "media": null,
  "status": "pending",
  "error": null,
  "templateName": null,
  "createdAt": "2026-11-06T14:32:10.000Z"
}

Enviar modelo do WhatsApp

POST/conversations/{id}/template

Envia um modelo aprovado pela Meta numa conversa do WhatsApp oficial (Cloud API), dentro ou fora da janela de 24 horas.

Escopo templates:send (Enviar modelos do WhatsApp)

  • idcaminhoobrigatório

    uuid

    Id da conversa.

  • namecorpoobrigatório

    texto, até 512

  • languagecorpoobrigatório

    texto, até 15

  • bodyParamscorpo

    lista de texto, até 30

Pedido em curl
curl -X POST "https://api.atendux.tech/public/v1/conversations/5d759f13-06d0-44b2-8bff-8c14994ecb91/template" \
  -H "Authorization: Bearer $ATENDUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "pedido_enviado",
  "language": "pt_BR",
  "bodyParams": [
    "Maria"
  ]
}'
Resposta 201
Resposta 201
{
  "id": "e7f29cc9-50f7-4ea2-be13-5936de962ea5",
  "conversationId": "58cbd88e-f2d9-4404-8bf2-8e5b88d0acc1",
  "direction": "in",
  "sender": "contact",
  "authorName": "Maria Souza",
  "type": "text",
  "text": "Olá! Meu pedido já saiu para entrega?",
  "media": null,
  "status": "pending",
  "error": null,
  "templateName": null,
  "createdAt": "2026-11-06T14:32:10.000Z"
}

Encerrar conversa

POST/conversations/{id}/close

Encerra e manda a pesquisa do encerramento, como no painel. Com `skipSurvey: true`, encerra sem a pesquisa.

Escopo conversations:write (Encerrar e transferir conversas)

  • idcaminhoobrigatório

    uuid

    Id da conversa.

  • skipSurveycorpo

    true ou false

    true encerra sem mandar a pesquisa de satisfação (padrão: false).

Pedido em curl
curl -X POST "https://api.atendux.tech/public/v1/conversations/6ee3aaeb-50e5-4bf2-9de8-543ecf9f2cc5/close" \
  -H "Authorization: Bearer $ATENDUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "skipSurvey": false
}'
Resposta 200
Resposta 200
{
  "id": "e3673131-8b28-4492-b654-4b780f566961",
  "status": "open",
  "contact": {
    "id": "ea51d183-bb2f-4c4e-a66d-fcda8e4e69e9",
    "name": "Maria Souza",
    "phone": "5548999990000",
    "email": "[email protected]"
  },
  "channel": {
    "id": "d714de26-f944-493a-9f68-9fbb26eb3d41",
    "type": "whatsapp_cloud",
    "name": "WhatsApp da loja"
  },
  "queue": {
    "id": "d522516e-4ee2-462e-93b3-f65b02dc3acd",
    "name": "Vendas"
  },
  "assignee": {
    "id": "58884fb8-1f5e-4640-93ef-c0c15c1a1b75",
    "name": "Ana Lima"
  },
  "tags": [
    {
      "id": "b971e09f-b242-4882-9a39-ca4a40298645",
      "name": "Cliente VIP",
      "color": "teal"
    }
  ],
  "unreadCount": 2,
  "lastMessageAt": "2026-11-06T14:32:10.000Z",
  "lastInboundAt": "2026-11-06T14:32:10.000Z",
  "createdAt": "2026-11-06T14:32:10.000Z",
  "closedAt": null
}

Atribuir conversa

POST/conversations/{id}/assign

Passa a conversa para uma pessoa da equipe que atende no setor dela.

Escopo conversations:write (Encerrar e transferir conversas)

  • idcaminhoobrigatório

    uuid

    Id da conversa.

  • userIdcorpoobrigatório

    uuid

    Id da pessoa da equipe que vai atender.

Pedido em curl
curl -X POST "https://api.atendux.tech/public/v1/conversations/b9fb8f72-ab2b-4b28-8351-ec57b9a9b6f9/assign" \
  -H "Authorization: Bearer $ATENDUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "21e1b1a7-1f9e-42e2-8433-86bc5f1a6611"
}'
Resposta 200
Resposta 200
{
  "id": "7ce5f308-fa6b-4c48-865a-c0c1929c7eb5",
  "status": "open",
  "contact": {
    "id": "3bb492e6-91b0-425c-a768-827fa4919119",
    "name": "Maria Souza",
    "phone": "5548999990000",
    "email": "[email protected]"
  },
  "channel": {
    "id": "85502213-3e24-4db2-8904-91187abd28e9",
    "type": "whatsapp_cloud",
    "name": "WhatsApp da loja"
  },
  "queue": {
    "id": "8fd7f3b3-6a20-41ce-9c91-4c3c61208729",
    "name": "Vendas"
  },
  "assignee": {
    "id": "d36203f3-39d0-473a-80a2-403e235b54bd",
    "name": "Ana Lima"
  },
  "tags": [
    {
      "id": "61c6a1b6-ecf1-4cf0-a66b-606374637ce1",
      "name": "Cliente VIP",
      "color": "teal"
    }
  ],
  "unreadCount": 2,
  "lastMessageAt": "2026-11-06T14:32:10.000Z",
  "lastInboundAt": "2026-11-06T14:32:10.000Z",
  "createdAt": "2026-11-06T14:32:10.000Z",
  "closedAt": null
}

Transferir conversa

POST/conversations/{id}/transfer

Transfere para um setor ou para uma pessoa, com nota interna opcional.

Escopo conversations:write (Encerrar e transferir conversas)

  • idcaminhoobrigatório

    uuid

    Id da conversa.

  • queueIdcorpo

    uuid

    Setor de destino.

  • userIdcorpo

    uuid

    Pessoa de destino.

  • notecorpo

    texto, até 500

    Nota interna da transferência.

Pedido em curl
curl -X POST "https://api.atendux.tech/public/v1/conversations/5175ff7c-ce0c-43b8-aac5-c3758dbad205/transfer" \
  -H "Authorization: Bearer $ATENDUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "queueId": "39c0ae51-ee5d-4d6a-9086-db98a57149d1",
  "note": "Cliente pediu a troca do pedido 1234."
}'
Resposta 200
Resposta 200
{
  "id": "db59baa6-cafe-48b4-85e5-f3779f242f81",
  "status": "open",
  "contact": {
    "id": "16e30650-15e3-4d60-8296-9ce93d62d25d",
    "name": "Maria Souza",
    "phone": "5548999990000",
    "email": "[email protected]"
  },
  "channel": {
    "id": "22e40221-966f-4dca-80d5-8cee61ce65b5",
    "type": "whatsapp_cloud",
    "name": "WhatsApp da loja"
  },
  "queue": {
    "id": "3723790d-f34e-41f2-b5d1-5c72fe1ae185",
    "name": "Vendas"
  },
  "assignee": {
    "id": "c4e16781-5d7f-4542-8969-851c59a48f25",
    "name": "Ana Lima"
  },
  "tags": [
    {
      "id": "b3e47a3c-7324-4370-8d10-cad52f9e1685",
      "name": "Cliente VIP",
      "color": "teal"
    }
  ],
  "unreadCount": 2,
  "lastMessageAt": "2026-11-06T14:32:10.000Z",
  "lastInboundAt": "2026-11-06T14:32:10.000Z",
  "createdAt": "2026-11-06T14:32:10.000Z",
  "closedAt": null
}

Consultas

Listar etiquetas

GET/tags

As etiquetas da empresa.

Escopo tags:read (Ver etiquetas)

Pedido em curl
curl "https://api.atendux.tech/public/v1/tags" \
  -H "Authorization: Bearer $ATENDUX_API_KEY"
Resposta 200
Resposta 200
{
  "tags": [
    {
      "id": "dc8e1d29-15c5-4332-af82-b9fab6e7a825",
      "name": "Cliente VIP",
      "color": "teal"
    }
  ]
}

Listar setores

GET/queues

Os setores e quem atende em cada um.

Escopo queues:read (Ver setores)

Pedido em curl
curl "https://api.atendux.tech/public/v1/queues" \
  -H "Authorization: Bearer $ATENDUX_API_KEY"
Resposta 200
Resposta 200
{
  "queues": [
    {
      "id": "c861f2c3-0121-445e-b83b-12cc101f5609",
      "name": "Vendas",
      "members": [
        {
          "userId": "f09c7408-e59c-435c-811a-1c01460202a5",
          "name": "Ana Lima"
        }
      ]
    }
  ]
}

Listar canais

GET/channels

Os canais da empresa, sem credenciais.

Escopo channels:read (Ver canais)

Pedido em curl
curl "https://api.atendux.tech/public/v1/channels" \
  -H "Authorization: Bearer $ATENDUX_API_KEY"
Resposta 200
Resposta 200
{
  "channels": [
    {
      "id": "e6c61a7b-d2eb-45f6-b639-e2d063b1f221",
      "type": "whatsapp_cloud",
      "name": "WhatsApp da loja",
      "status": "connected",
      "phoneNumber": "5548999990000",
      "official": true
    }
  ]
}

Webhooks pela API

Listar webhooks

GET/webhooks

Os webhooks da empresa (até 10), sem os segredos.

Escopo webhooks:manage (Gerenciar webhooks)

Pedido em curl
curl "https://api.atendux.tech/public/v1/webhooks" \
  -H "Authorization: Bearer $ATENDUX_API_KEY"
Resposta 200
Resposta 200
{
  "webhooks": [
    {
      "id": "74565f57-5615-4c06-90ca-1f64d6317311",
      "url": "https://erp.suaempresa.com.br/webhooks/atendux",
      "description": "ERP da loja",
      "events": [
        "message.received"
      ],
      "includeContent": false,
      "includeContact": false,
      "enabled": true,
      "disabledReason": null,
      "failingSince": null,
      "lastSuccessAt": "2026-11-06T14:32:10.000Z",
      "createdAt": "2026-11-06T14:32:10.000Z",
      "updatedAt": "2026-11-06T14:32:10.000Z"
    }
  ]
}

Criar webhook

POST/webhooks

Cria um webhook. O segredo (whsec_...) volta uma vez só, nesta resposta. acceptResponsibility: true confirma: "Este endereço é de um sistema da empresa ou de um fornecedor contratado por ela, e a empresa responde pelo que ele faz com os dados."

Escopo webhooks:manage (Gerenciar webhooks)

  • urlcorpoobrigatório

    texto, até 2.000

  • descriptioncorpo

    texto, até 120 ou null

  • eventscorpoobrigatório

    lista de message.received | message.sent | message.status_updated | conversation.created | conversation.assigned | conversation.transferred | conversation.closed | conversation.reopened | contact.created | contact.updated | survey.answered

  • includeContentcorpo

    true ou false

  • includeContactcorpo

    true ou false

  • acceptResponsibilitycorpoobrigatório

    true

Pedido em curl
curl -X POST "https://api.atendux.tech/public/v1/webhooks" \
  -H "Authorization: Bearer $ATENDUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://erp.suaempresa.com.br/webhooks/atendux",
  "description": "ERP da loja",
  "events": [
    "message.received"
  ],
  "includeContent": false,
  "includeContact": false,
  "acceptResponsibility": true
}'
Resposta 201
Resposta 201
{
  "webhook": {
    "id": "8078690a-1975-4280-85cf-3b077b9f0259",
    "url": "https://erp.suaempresa.com.br/webhooks/atendux",
    "description": "ERP da loja",
    "events": [
      "message.received"
    ],
    "includeContent": false,
    "includeContact": false,
    "enabled": true,
    "disabledReason": null,
    "failingSince": null,
    "lastSuccessAt": "2026-11-06T14:32:10.000Z",
    "createdAt": "2026-11-06T14:32:10.000Z",
    "updatedAt": "2026-11-06T14:32:10.000Z"
  },
  "secret": "whsec_7Hq2mZ9xKp4vT1sLc8NwR3bYdF6gJ0eA5uQiVoXkE2r"
}

Ver webhook

GET/webhooks/{id}

Um webhook, sem o segredo.

Escopo webhooks:manage (Gerenciar webhooks)

  • idcaminhoobrigatório

    uuid

    Id do webhook.

Pedido em curl
curl "https://api.atendux.tech/public/v1/webhooks/f221bf97-5827-42ca-b93b-0dc841de0311" \
  -H "Authorization: Bearer $ATENDUX_API_KEY"
Resposta 200
Resposta 200
{
  "id": "6d1c8fad-9579-4d42-b612-f558d9363c09",
  "url": "https://erp.suaempresa.com.br/webhooks/atendux",
  "description": "ERP da loja",
  "events": [
    "message.received"
  ],
  "includeContent": false,
  "includeContact": false,
  "enabled": true,
  "disabledReason": null,
  "failingSince": null,
  "lastSuccessAt": "2026-11-06T14:32:10.000Z",
  "createdAt": "2026-11-06T14:32:10.000Z",
  "updatedAt": "2026-11-06T14:32:10.000Z"
}

Editar, ligar ou desligar webhook

PATCH/webhooks/{id}

Muda só os campos enviados. Trocar a URL pede acceptResponsibility: true de novo. enabled: true liga de novo e zera a contagem de falhas.

Escopo webhooks:manage (Gerenciar webhooks)

  • idcaminhoobrigatório

    uuid

    Id do webhook.

  • urlcorpo

    texto, até 2.000

  • descriptioncorpo

    texto, até 120 ou null

  • eventscorpo

    lista de message.received | message.sent | message.status_updated | conversation.created | conversation.assigned | conversation.transferred | conversation.closed | conversation.reopened | contact.created | contact.updated | survey.answered

  • includeContentcorpo

    true ou false

  • includeContactcorpo

    true ou false

  • enabledcorpo

    true ou false

  • acceptResponsibilitycorpo

    true

Pedido em curl
curl -X PATCH "https://api.atendux.tech/public/v1/webhooks/e987aada-578f-4066-bf2d-10673769db59" \
  -H "Authorization: Bearer $ATENDUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://erp.suaempresa.com.br/webhooks/atendux",
  "description": "ERP da loja",
  "events": [
    "message.received"
  ],
  "includeContent": false,
  "includeContact": false,
  "enabled": true,
  "acceptResponsibility": true
}'
Resposta 200
Resposta 200
{
  "id": "d242e0c0-7ded-4c60-b218-5e3979055715",
  "url": "https://erp.suaempresa.com.br/webhooks/atendux",
  "description": "ERP da loja",
  "events": [
    "message.received"
  ],
  "includeContent": false,
  "includeContact": false,
  "enabled": true,
  "disabledReason": null,
  "failingSince": null,
  "lastSuccessAt": "2026-11-06T14:32:10.000Z",
  "createdAt": "2026-11-06T14:32:10.000Z",
  "updatedAt": "2026-11-06T14:32:10.000Z"
}

Excluir webhook

DELETE/webhooks/{id}

Exclui o webhook e o registro das entregas dele.

Escopo webhooks:manage (Gerenciar webhooks)

  • idcaminhoobrigatório

    uuid

    Id do webhook.

Pedido em curl
curl -X DELETE "https://api.atendux.tech/public/v1/webhooks/9fa60ca4-5207-4d5a-b89e-615d7000c455" \
  -H "Authorization: Bearer $ATENDUX_API_KEY"

Responde 204, sem corpo.

Ver entregas

GET/webhooks/{id}/deliveries

As entregas dos últimos 30 dias, das mais novas para as mais antigas.

Escopo webhooks:manage (Gerenciar webhooks)

  • idcaminhoobrigatório

    uuid

    Id do webhook.

  • statusconsulta

    pending | retrying | succeeded | failed

  • cursorconsulta

    texto, até 200

  • limitconsulta

    inteiro, 1 a 100

Pedido em curl
curl "https://api.atendux.tech/public/v1/webhooks/eff38959-f917-43a2-8588-78d44bd75905/deliveries?status=pending" \
  -H "Authorization: Bearer $ATENDUX_API_KEY"
Resposta 200
Resposta 200
{
  "deliveries": [
    {
      "id": "fac5c78b-b073-4636-863c-d1186bcce419",
      "webhookId": "83298ea8-b823-413e-9f94-ec4d8f2ba0f9",
      "event": "message.received",
      "eventId": "97baa529-f3bb-4172-8661-90c484c888b1",
      "status": "pending",
      "attempt": 1,
      "responseStatus": 200,
      "latencyMs": 182,
      "error": null,
      "test": false,
      "nextAttemptAt": null,
      "createdAt": "2026-11-06T14:32:10.000Z",
      "updatedAt": "2026-11-06T14:32:10.000Z"
    }
  ],
  "nextCursor": null
}