> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatnorris.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Zapier

> Como conectar o ChatNorris ao Zapier: triggers, ação de envio de mensagens e permissões usadas.

O ChatNorris tem um app público no diretório do Zapier (**status: Beta**). Não é uma integração à parte com lógica própria: ele se conecta usando uma **API key da API v2** e expõe um subconjunto desses mesmos endpoints como triggers e ações do Zapier, sem que você precise montar requests HTTP manualmente.

> [!NOTE]
>
> Requer uma API key com acesso à API v2 — disponível nos planos **Standard** e **Premium** (veja [Introdução à API](https://docs.chatnorris.ai/pt/api-referencia/introduccion.md)).

***

## Conectar sua conta

1. No ChatNorris, acesse **Configurações → Chaves de API** e crie uma key. Anote-a: ela só é exibida uma vez.
2. No Zapier, procure o app **ChatNorris** ao criar um Zap.
3. Cole a API key no campo **API Key** da conexão. O Zapier testa a conexão contra `GET /api/v2/project` e, se ela for válida, mostra o nome da sua organização.
4. Você pode reutilizar a mesma conexão em vários Zaps.

> [!TIP]
>
> Use uma API key dedicada ao Zapier (não a que você já usa em outra integração) para poder revogá-la de forma independente em **Configurações → Chaves de API** se algum dia precisar.

***

## Triggers

Os triggers funcionam por **polling**: o Zapier consulta a API no intervalo correspondente ao seu plano do Zapier e remove automaticamente os resultados já vistos.

| Trigger | O que dispara | Filtro opcional | Escopo necessário |
| - | - | - | - |
| **New Contact** | Um novo lead capturado por um agente | Agente (todos por padrão) | `leads:read` |
| **New Conversation** | Uma nova conversa iniciada | Agente (todos por padrão) | `conversations:read` |

O campo **Agent** é uma lista suspensa que traz a lista real dos seus agentes (usa `chatbots:read` internamente); deixe-o vazio para escutar todos os agentes da organização.

> [!NOTE]
>
> **New Conversation** também dispara para conversas criadas pela própria API (canal `api`) — por exemplo, se outra integração usa a ação **Send Message** para iniciar uma conversa nova.

***

## Ação: Send Message

Envia uma mensagem a um agente e aguarda a resposta dele — o mesmo `POST /api/v2/chatbots/:id/chat` da API.

| Campo | Obrigatório | Descrição |
| - | - | - |
| Chatbot | Sim | Agente que vai responder (lista suspensa) |
| Message | Sim | Texto da mensagem a enviar |
| Conversation ID | Não | Se você informar, continua uma conversa existente em vez de criar uma nova |

A ação retorna `reply` (a resposta do agente) e `conversation_id`, que você pode encadear no restante do Zap — por exemplo, para reencaminhar a resposta por email ou Slack, ou para usá-lo novamente como `Conversation ID` em um passo posterior e manter a conversa.

Requer o scope `chat:write`.

***

## Permissões que cada parte usa

| Uso no Zapier | Scope |
| - | - |
| New Contact | `leads:read` |
| New Conversation | `conversations:read` |
| Lista suspensa de agentes (nos triggers e na ação) | `chatbots:read` |
| Send Message | `chat:write` |

As API keys criadas em **Configurações → Chaves de API** têm acesso completo (`*`), então cobrem todos esses usos: não é preciso escolher permissões.

***

## Limites conhecidos

* Não existe um trigger de "nova mensagem" dentro de uma conversa — apenas nova conversa e novo lead.
* Não há uma ação para atualizar um lead existente: a API pública v2 ainda não expõe esse endpoint.
* Os dados de um lead vêm com os campos base (nome, email, telefone, data) mais `contact_properties` (empresa, cargo, cidade etc.) e `custom_fields`; eles não vêm achatados campo a campo, a menos que você os mapeie manualmente no Zap.

***

## Veja também

* [Introdução à API](https://docs.chatnorris.ai/pt/api-referencia/introduccion.md) — autenticação, scopes e formato de resposta.
* [n8n](https://docs.chatnorris.ai/pt/api-referencia/n8n.md) — alternativa self-hosted ou open-source ao Zapier, com mais operações (incluindo base de conhecimento).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.