Para desenvolvedores

Se o script embed e o painel bastam, comece em Chat com IA no site. Esta página resume a API pública para integrações custom.

Em poucas palavras

Base: https://api.notifique.me/public/ai-widget
Sem API Key de workspace. Segurança por chave pública do widget, domínios permitidos e token de sessão.
Rotas, headers e respostas completas: referência da API na aba Chat no site.

Fluxo típico

Obter configuração do widget (tema, textos, regras de identificação). O script embed faz isso ao carregar.
Criar ou retomar sessão com visitorClientId e dados do visitante (se o modo pedir).
Enviar mensagem com sessionToken e text no body (veja exemplos abaixo).
Se a resposta vier com status handoff ou automation, use polling para buscar mensagens novas.
Com OTP ativo: pedir código e confirmar código antes de liberar o chat.

Obter configuração

Use a operação Obter configuração do widget na referência da API. Resposta comum:

{
  "success": true,
  "data": {
    "name": "Assistente da Loja",
    "status": "ACTIVE",
    "identificationMode": "OPTIONAL",
    "identificationFieldMode": "EMAIL",
    "requireIdentityOtp": false,
    "theme": { "primaryColor": "#6366f1", "position": "right" },
    "maxMessagesPerSession": 50,
    "messageCooldownMs": 1000,
    "welcomeText": "Olá! Como posso ajudar?",
    "suggestedQuestions": ["Quais são os preços?", "Como funciona a entrega?"]
  }
}

Criar ou retomar sessão

Use a operação Criar sessão na referência da API.

{
  "visitorClientId": "id-salvo-no-navegador",
  "name": "Maria Silva",
  "email": "maria@exemplo.com",
  "phone": "5511999999999"
}

Campo	Quando enviar
`visitorClientId`	Sempre
`name`	Modo não anônimo
`email` / `phone`	Conforme configuração

Site com login (verificação automática):

{
  "identityPayload": {
    "email": "maria@exemplo.com",
    "exp": 1730000000,
    "publicKey": "ntfw_xxx",
    "v": 1
  },
  "identitySignature": "assinatura-hex-aqui"
}

Guarde o sessionToken da resposta e envie-o no body das chamadas seguintes (sessionToken). Resposta típica:

{
  "success": true,
  "data": {
    "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "sessionId": "clsession123",
    "identityVerified": false,
    "messages": []
  }
}

Enviar mensagem

Use a operação Enviar mensagem na referência da API.

{
  "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "text": "Quanto custa o plano Pro?",
  "clientMessageId": "id-unico-para-evitar-duplicata"
}

Resposta da IA:

{
  "success": true,
  "data": {
    "messageId": "id-da-mensagem",
    "replyText": "O plano Pro custa R$ 97/mês e inclui...",
    "status": "assistant"
  }
}

Handoff (transferência humana):

{
  "success": true,
  "data": {
    "messageId": "id-da-mensagem",
    "replyText": null,
    "status": "handoff"
  }
}

Status	Significado
`assistant`	IA respondeu
`handoff`	Transferiu para humano. Use polling.
`automation`	Automação disparada. Use polling.

Buscar mensagens novas (polling)

Use a operação Listar mensagens na referência da API, com parâmetro after (timestamp). Recomendado: polling a cada 2 s, por até 3 minutos, quando status for handoff ou automation.

OTP

Pedir código: operação Solicitar OTP com { "sessionToken": "..." }
Confirmar código: operação Verificar OTP com { "sessionToken": "...", "code": "482913" }

Erros comuns

Código	Significado
403	Domínio não permitido, OTP pendente ou widget pausado
429	Rate limit
422	Máximo de mensagens ou cooldown
401	Sessão inválida ou expirada

Painel (uso interno)

Endpoints de gestão do widget (listar, criar, atualizar, rotacionar chaves) exigem login no dashboard. Detalhes na referência da API na aba Chat no site.

Todos os tipos de envio

Na referência da API (aba Chat no site), abra Enviar mensagem no widget (POST /v1/...) e escolha o exemplo no playground: Sessão, Mensagem, OTP.

Próximos passos

Segurança: modos de identificação
Dicas
Chat com IA no site

​Em poucas palavras

​Fluxo típico

​Obter configuração

​Criar ou retomar sessão

​Enviar mensagem

​Buscar mensagens novas (polling)

​OTP

​Erros comuns

​Painel (uso interno)

​Todos os tipos de envio

​Próximos passos

Em poucas palavras

Fluxo típico

Obter configuração

Criar ou retomar sessão

Enviar mensagem

Buscar mensagens novas (polling)

OTP

Erros comuns

Painel (uso interno)

Todos os tipos de envio

Próximos passos