# API PicChat

> API pública da PicChat para qualquer conta: consultas da conta (/v1), cadastro de contatos e disparo de mensagens por automação. Base URL https://api.picchat.com.br, autenticação Authorization: Bearer <token>. MCP remoto em https://mcp.picchat.io/mcp.

## Guias
- [Comece por aqui](https://docs.picchat.com.br/)
- [Autenticação e tokens](https://docs.picchat.com.br/guias/autenticacao)
- [Como funciona o envio](https://docs.picchat.com.br/guias/como-funciona-o-envio)
- [Cadastrar e atualizar contatos](https://docs.picchat.com.br/guias/contatos)
- [Disparar mensagens por automação](https://docs.picchat.com.br/guias/disparos)
- [Ler conversas e dados da conta](https://docs.picchat.com.br/guias/consultas)
- [HubSpot](https://docs.picchat.com.br/guias/hubspot)
- [RD Station Marketing](https://docs.picchat.com.br/guias/rd-station)
- [Códigos HTTP e erros](https://docs.picchat.com.br/guias/erros)
- [Paginação e filtros](https://docs.picchat.com.br/guias/paginacao)
- [Limites e boas práticas](https://docs.picchat.com.br/guias/boas-praticas)

## API Reference
- [GET /v1/me](https://docs.picchat.com.br/referencia/getMe): Consultar a conta do token
- [GET /v1/tickets](https://docs.picchat.com.br/referencia/listTickets): Listar tíquetes
- [GET /v1/tickets/{id}](https://docs.picchat.com.br/referencia/getTicket): Consultar tíquete
- [GET /v1/tickets/{id}/messages](https://docs.picchat.com.br/referencia/listTicketMessages): Listar mensagens do tíquete
- [GET /v1/messages](https://docs.picchat.com.br/referencia/listMessages): Listar mensagens
- [GET /v1/messages/{id}](https://docs.picchat.com.br/referencia/getMessage): Consultar mensagem
- [GET /v1/contacts](https://docs.picchat.com.br/referencia/listContacts): Listar contatos
- [GET /v1/contacts/{id}](https://docs.picchat.com.br/referencia/getContact): Consultar contato
- [GET /v1/contacts/{id}/tickets](https://docs.picchat.com.br/referencia/listContactTickets): Listar tíquetes do contato
- [POST /contacts/create-or-update](https://docs.picchat.com.br/referencia/createOrUpdateContact): Criar ou atualizar contato
- [GET /contacts/find](https://docs.picchat.com.br/referencia/findContact): Buscar contato por celular ou e-mail
- [GET /v1/properties](https://docs.picchat.com.br/referencia/listProperties): Listar propriedades
- [GET /v1/properties/{id}](https://docs.picchat.com.br/referencia/getProperty): Consultar propriedade
- [GET /v1/tags](https://docs.picchat.com.br/referencia/listTags): Listar tags
- [GET /v1/lists](https://docs.picchat.com.br/referencia/listLists): Listar listas
- [GET /v1/lists/{id}](https://docs.picchat.com.br/referencia/getList): Consultar lista
- [GET /v1/lists/{id}/contacts](https://docs.picchat.com.br/referencia/listListContacts): Listar contatos da lista
- [GET /v1/notes](https://docs.picchat.com.br/referencia/listNotes): Listar notas
- [GET /v1/ticket-status](https://docs.picchat.com.br/referencia/listTicketStatus): Listar status de tíquete
- [GET /v1/users](https://docs.picchat.com.br/referencia/listUsers): Listar usuários
- [GET /v1/campaigns](https://docs.picchat.com.br/referencia/listCampaigns): Listar campanhas
- [GET /v1/campaigns/{id}](https://docs.picchat.com.br/referencia/getCampaign): Consultar campanha
- [GET /v1/automations](https://docs.picchat.com.br/referencia/listAutomations): Listar automações
- [GET /v1/automations/{id}](https://docs.picchat.com.br/referencia/getAutomation): Consultar automação
- [POST /automations/enrollments](https://docs.picchat.com.br/referencia/enrollInAutomation): Inscrever contatos em uma automação
- [POST /automations/enrollments/hubspot](https://docs.picchat.com.br/referencia/enrollFromHubspot): Inscrever contato vindo do HubSpot
- [POST /contacts/rdstation](https://docs.picchat.com.br/referencia/contactFromRdstation): Receber leads do RD Station Marketing
- [GET /v1/channels](https://docs.picchat.com.br/referencia/listChannels): Listar canais
- [GET /v1/channels/{id}](https://docs.picchat.com.br/referencia/getChannel): Consultar canal
- [GET /v1/templates](https://docs.picchat.com.br/referencia/listTemplates): Listar modelos
- [GET /v1/templates/{id}](https://docs.picchat.com.br/referencia/getTemplate): Consultar modelo
- [GET /v1/assistants](https://docs.picchat.com.br/referencia/listAssistants): Listar assistentes de IA
- [GET /v1/assistants/{id}](https://docs.picchat.com.br/referencia/getAssistant): Consultar assistente de IA
- [GET /v1/knowledge-bases](https://docs.picchat.com.br/referencia/listKnowledgeBases): Listar bases de conhecimento
- [GET /v1/knowledge-bases/{id}](https://docs.picchat.com.br/referencia/getKnowledgeBase): Consultar base de conhecimento

## MCP
- [O que é o MCP da PicChat](https://docs.picchat.com.br/mcp)
- [Instalação](https://docs.picchat.com.br/mcp/instalacao)
- [Token e permissões](https://docs.picchat.com.br/mcp/permissoes)
- [Catálogo de tools](https://docs.picchat.com.br/mcp/tools)
- [Exemplos de pedidos](https://docs.picchat.com.br/mcp/exemplos)
- [Segurança](https://docs.picchat.com.br/mcp/seguranca)

## Comece por aqui (texto completo)

# Comece por aqui

A API da PicChat conecta o seu sistema à sua conta: você consulta conversas, contatos e campanhas, mantém os contatos atualizados a partir do seu CRM ou site e dispara mensagens de WhatsApp pelas automações que já existem no painel. Tudo com o token da própria conta, sem contratar nada à parte.

> [!INFO]
> Esta documentação cobre a API que **qualquer conta PicChat** pode usar. Se você só quer consultar a sua conta conversando com o Claude, vá direto para o [MCP](/mcp) — ele usa esta mesma API por baixo.

## O que dá pra fazer

| Você quer… | Use |
|---|---|
| Ler tíquetes, mensagens, contatos, listas, campanhas, automações, canais, templates e assistentes | [Consultas `/v1`](/guias/consultas) |
| Criar ou atualizar um contato vindo do seu site, CRM ou formulário | [`POST /contacts/create-or-update`](/guias/contatos) |
| Gravar propriedades personalizadas num contato (etapa do funil, plano, cidade…) | [Propriedades no create-or-update](/guias/contatos#propriedades-personalizadas) |
| Enviar uma mensagem de WhatsApp para um ou vários contatos | [Disparo por automação](/guias/disparos) |
| Consultar a conta pelo Claude, sem escrever código | [MCP](/mcp) |

## Ambiente e base URL

| Ambiente | Base URL |
|---|---|
| Produção | `https://api.picchat.com.br` |

> [!WARN]
> **Não existe sandbox.** Toda chamada age na sua conta de verdade: `POST` cria contatos e dispara mensagens reais, que consomem créditos. Para testar, use um contato seu e uma automação de teste (veja [Como funciona o envio](/guias/como-funciona-o-envio)).

## Autenticação

Toda requisição leva o token da conta no header `Authorization`:

```http
Authorization: Bearer SEU_TOKEN
```

O token é gerado no painel em **Configurações → Integrações** ([abrir](https://app.picchat.com.br/configuration/integrations)) e aparece uma vez só — guarde num cofre de segredos. Ele age como o usuário que o criou: enxerga o que esse usuário enxerga no painel. Detalhes em [Autenticação e tokens](/guias/autenticacao).

| Situação | Resposta |
|---|---|
| Token ausente, inválido ou revogado | `498` · `errorCode` `API_TOKEN_INVALID` ou `API_TOKEN_REVOKED` |
| Usuário do token sem permissão para a consulta | `403` · `API_V1_PERMISSION_DENIED` |
| `account_id` de outra conta na query ou no corpo | `403` · `API_ACCOUNT_ID_NOT_IN_TOKEN` |

Todos os erros seguem o mesmo formato — veja [Códigos HTTP e erros](/guias/erros).

> [!INFO]
> A API responde **498** (e não 401) para token inválido. Trate os dois códigos do mesmo jeito no seu cliente HTTP.

## Primeira chamada em 2 minutos

1. Gere um token em **Configurações → Integrações**.
2. Rode no terminal:

```bash
curl https://api.picchat.com.br/v1/me \
  --header 'Authorization: Bearer SEU_TOKEN'
```

3. A resposta traz a conta do token — nome, plano, créditos, canais e usuários — e, em `access`, quem é o usuário, o grupo de permissão e o que ele pode consultar. Se chegou aqui, o token funciona.

Prefere testar sem terminal? Cada página da [API Reference](/referencia) tem um console: cole o token na coluna da direita e clique em **Testar requisição**.

## Como esta documentação está organizada

- **Guias** — o passo a passo de cada caso de uso, com exemplos completos.
- **API Reference** — cada endpoint com parâmetros, respostas, exemplos em cURL, Node, Python e PHP e o console para testar.
- **MCP** — como ligar a sua conta ao Claude (claude.ai, Claude Code, Claude Desktop, Cursor).
- **Changelog** — o que mudou e quando.

Em qualquer página, o botão **Copiar para IA** copia o conteúdo em Markdown para você colar no seu assistente. O índice completo para agentes fica em [`/llms.txt`](/llms.txt).

## Próximos passos

<div class="cards">
<a href="/guias/autenticacao"><strong>Autenticação e tokens</strong><span>Tipos de token, permissões e revogação.</span></a>
<a href="/guias/disparos"><strong>Disparar mensagens</strong><span>Inscreva contatos numa automação e envie templates.</span></a>
<a href="/guias/contatos"><strong>Sincronizar contatos</strong><span>Crie ou atualize contatos e propriedades.</span></a>
<a href="/referencia"><strong>API Reference</strong><span>Todos os endpoints com console para testar.</span></a>
<a href="/mcp"><strong>MCP</strong><span>Consulte a conta conversando com o Claude.</span></a>
</div>