Saltar para o conteúdo principal
Cada mudança no contrato da API pública aparece aqui: novos endpoints e campos no dia em que saem, e a rara correção feita antes de um campo ter uso real. Construa sua integração para ignorar os campos que não conhece, e confira esta página quando algo mudar.
​
Limite de capacidade
  • Novo 503 server_busy: quando uma chave tem solicitações demais em andamento ao mesmo tempo, ou a API está no limite de capacidade, uma solicitação retorna 503 com Retry-After: 1. Ela não foi executada e não conta contra o seu limite de uso; tente novamente. Enviar até 100 destinatários por envio de modelo, em vez de uma chamada por destinatário, evita isso. Veja limites de uso.
​
Webhooks
  • conversation.assigned traz mais dados: o nome e o email do colega (assignee), como foi atribuída (strategy, assigned_by, self_assigned) e uma url para a conversa, para que uma ferramenta sem código publique um alerta útil sem chamar a API. Veja o catálogo de eventos.
​
Formulários do WhatsApp
​
Webhooks
A Ciarem agora pode chamar o seu servidor quando algo muda, então você não precisa mais consultar a API repetidamente. Comece pelo guia de webhooks.
  • Endpoints de webhook: cadastre até 10 URLs HTTPS por organização e escolha quais eventos cada uma recebe (/v1/webhook-endpoints: listar, criar, ler, atualizar, excluir). Também disponível para administradores no painel em Configurações → Webhooks.
  • Dez tipos de evento: contact.created, contact.updated, contact.deleted, contact.merged, contact.funnel_stage.changed, contact.owner.changed, conversation.created, conversation.assigned, conversation.closed e messages.inbound. Os eventos de contato carregam o contato completo. Veja o catálogo de eventos.
  • Solicitações assinadas: cada solicitação carrega um cabeçalho Ciarem-Signature, um HMAC-SHA256 feito com o segredo de assinatura whsec_ do endpoint. Veja Verificar assinaturas.
  • Novas tentativas e um registro de entregas: uma entrega com falha é tentada de novo por até 3 dias, e cada entrega dos últimos 30 dias pode ser lida com GET /v1/webhook-endpoints/{id}/deliveries e enviada novamente com POST /v1/webhook-deliveries/{id}/redeliver. Veja Entregas e novas tentativas.
  • Eventos de teste: POST /v1/webhook-endpoints/{id}/test envia um evento agora mesmo e retorna o que o seu servidor respondeu. GET /v1/webhook-event-samples retorna o corpo de exemplo de cada tipo de evento.
  • Incluído nos mesmos planos da API: Growth, Scale e o teste gratuito.
​
Descadastro de marketing por WhatsApp
  • Os contatos agora incluem marketing_opt_out (booleano, somente leitura): true quando o contato se descadastrou do marketing por WhatsApp. Não pode ser alterado pela API. Veja Descadastro de marketing por WhatsApp.
  • POST /v1/templates/{id}/send: um modelo de marketing não é enviado a um destinatário cujo marketing_opt_out é true. A solicitação é aceita mesmo assim e os demais destinatários são enviados; o destinatário descadastrado não recebe o envio nem é cobrado. Os modelos de utilidade e autenticação não mudam. Leia marketing_opt_out no contato para deixar esses destinatários de fora desde o início.
​
A API chega ao plano Growth
  • A API agora está incluída no plano Growth, não apenas no Scale. O Growth recebe todos os endpoints com um orçamento de 10 solicitações/segundo; o Scale continua em 20 solicitações/segundo e o teste em 5 solicitações/segundo. As chaves criadas durante um teste que continuou no Growth voltam a funcionar sem nenhuma alteração.
  • Mudança incompatível: scale_plan_required agora é plan_upgrade_required. O detalhe do 403 para um plano ativo sem a API (Solo) foi renomeado, porque o Scale deixou de ser o único plano que a inclui. Se a sua integração compara com o texto antigo, atualize-a. Veja Autenticação.
​
Os filtros de data de contatos usam datas absolutas
  • GET /v1/contacts: property_filter não aceita mais datas relativas. Uma condição sobre uma propriedade DATE recebe uma data YYYY-MM-DD, por exemplo custom_birthday:gte:2026-09-01. Um valor preset: como preset:1w agora retorna 400 com invalid_property_filter. Elas nunca foram documentadas: são resolvidas no fuso horário de quem está vendo o painel, algo que uma integração não controla. Calcule as datas do seu lado.
  • tz agora está documentado em GET /v1/contacts: o fuso horário IANA em que created_from / created_to são lidos. Por padrão usa o fuso horário da organização e, se não houver, UTC.
​
Acesso no teste gratuito, limites por segundo e 403 que dizem o que fazer
  • A API está aberta durante o teste gratuito. Uma organização em teste recebe todos os endpoints, com um orçamento menor, para construir e testar uma integração antes de pagar.
  • Os limites de uso agora são por segundo: 20 solicitações/segundo no Scale, 5 solicitações/segundo durante o teste, compartilhadas entre as chaves da organização. Os cabeçalhos X-RateLimit-* não mudam; Retry-After em um 429 agora é sempre 1.
  • GET /v1/me ganha trial (booleano), que é true enquanto a organização está no teste gratuito. plan agora informa o código real do plano em vez de sempre "scale".
  • 403 mais claros. scale_plan_required agora significa apenas que a organização está em um plano ativo abaixo do Scale e precisa fazer upgrade. Dois novos detalhes cobrem o resto: trial_expired (o teste terminou sem método de pagamento) e subscription_required (cancelada, ou suspensa por falta de pagamento). Veja Autenticação.
​
Modelos do WhatsApp, envios e campanhas
A API já pode enviar.
  • Modelos do WhatsApp: listar, ler, criar e excluir (/v1/templates). Criar um modelo também o envia à Meta para aprovação na mesma chamada, então ele volta como PENDING; consulte-o até a Meta mudá-lo para APPROVED ou REJECTED.
  • GET /v1/templates/{id}/send-requirements: o que um modelo precisa preenchido antes de poder ser enviado. Inclui os tokens de variáveis, quais deles se resolvem sozinhos a partir do contato, slots de catálogo, botões de URL dinâmicos, superfícies de mídia, e o motivo quando um modelo nunca pode ser enviado. Leia isso antes do primeiro envio em vez de descobrir por meio de 422s.
  • POST /v1/templates/{id}/send: até 100 destinatários em uma chamada, cada um identificado por contact_id ou phone e carregando suas próprias variables, url_suffixes, coupon_code, lto_expiration e mídia. recipients aceita um único objeto ou um array, então enviar para uma pessoa não precisa de embrulho. Cabeçalhos de mídia aceitam uma URL pública (header_media_url / card_media_urls), baixada no servidor. Retorna 202 e a campanha que criou.
    • Um phone que não corresponde a nenhum contato cria um, então um envio pode fazer seu CRM crescer.
    • Envie Idempotency-Key e repetir é seguro: a mesma chave devolve a campanha original por 24 horas em vez de enviar de novo.
    • A requisição é recusada inteira (nada enfileirado, nada cobrado) se faltar uma variável, se uma chave não for usada pelo modelo, se uma URL de mídia não puder ser baixada, ou se o lote exceder o que resta do limite de mensagens de 24 horas do WhatsApp.
  • Campanhas: GET /v1/broadcasts e GET /v1/broadcasts/{id} para o progresso (sent / failed / pending sempre somam requested), GET /v1/broadcasts/{id}/recipients para o resultado de cada destinatário, e POST /v1/broadcasts/{id}/cancel para abandonar o restante não enviado. Mensagens já aceitas pelo WhatsApp não podem ser recuperadas.
  • GET /v1/channels/whatsapp/phones: os números conectados de onde um envio pode sair, para que channel_id seja descobrível. Opcional quando sua conta do WhatsApp tem exatamente um número; obrigatório quando tem mais.
​
Lançamento da v1
A primeira superfície pública da API da Ciarem:
  • Contatos: CRUD completo (/v1/contacts).
  • Metadados de CRM: propriedades e etapas do funil, CRUD completo (/v1/properties, /v1/funnel-stages).
  • Conversas: histórico somente leitura (/v1/conversations), cada mensagem com um sender de contact, agent, ai ou system.
  • /v1/me: identidade da organização, plano, fuso horário e idioma.
  • Chaves de API oak_ vinculadas à organização, 60 solicitações/minuto por organização.