API v1 · 135 rotas · avisos assinados · MCP

API para desenvolvedores

Integre o seu ERP, a sua loja ou a sua automação à NossoIA — com as mesmas regras e travas do sistema.

Para o seu sistema (ERP, loja virtual, planilha, n8n, Make, Zapier) agir dentro do CRM — cadastrar e etiquetar clientes, mandar e responder mensagens em todos os canais, conduzir o atendimento, marcar compromissos, criar tarefas, disparar campanhas, publicar no Instagram, ler relatórios e ligações — e para receber um aviso quando algo acontece lá dentro. São 135 rotas, todas descritas abaixo.

Endereço base: https://app.nossoia.com/api/v1

Formato: JSON em UTF-8 · datas ISO 8601 com fuso · toda resposta traz o cabeçalho X-Pedido-Id

Em três passos

No CRM, um administrador abre API e Webhooks e cria uma chave, marcando só as permissões que o seu sistema precisa.
Guarde a chave no servidor do seu sistema — ela aparece uma vez só. Nunca no navegador nem em aplicativo de celular.
Teste:

curl 'https://app.nossoia.com/api/v1/eu' \
  -H 'Authorization: Bearer icrm_live_…'

A resposta diz a empresa, em nome de quem a chave age, as permissões e os limites.

Chave e permissões

Mande a chave em todo pedido: Authorization: Bearer <chave> (ou no cabeçalho X-Api-Key). A empresa vem da chave — nenhum pedido escolhe empresa. A chave age em nome da pessoa que a criou: vale o perfil dela no CRM e o que ela enxerga (fila, equipe, carteira), limitado às permissões marcadas na chave.

icrm_live_… age de verdade. icrm_test_… confere tudo (permissão, alcance, dados) e responde "simulado": true sem gravar, enviar, publicar ou ligar — use para desenvolver.
A chave pode ter validade e lista de IPs permitidos, e é revogada na hora pelo CRM.
Pessoa dona da chave desativada, ou sem acesso à empresa: a chave para de funcionar.

As permissões

Permissão	O que libera
`clientes:ler`	Ler clientes. Buscar e listar clientes, ver o funil
`clientes:escrever`	Criar e editar clientes. Cadastrar, atualizar e mover no funil
`clientes:excluir` sensível	Excluir clientes. Apagar cliente de vez (o mesmo excluir do funil). Até 100 por dia
`dados-pessoais:ler` sensível	Ver CPF e dados pessoais. Sem este escopo o CPF nem aparece na resposta
`etiquetas:ler`	Ler etiquetas. Listar etiquetas e o histórico de aplicação
`etiquetas:aplicar`	Aplicar e remover etiquetas. Etiquetar clientes — dispara a automação da etiqueta
`etiquetas:gerenciar`	Criar e editar etiquetas. Mexer no cadastro de etiquetas
`mensagens:enviar` sensível	Enviar mensagens. Mandar texto, mídia e template, e responder conversas em qualquer canal
`mensagens:ler`	Ver situação de mensagens. Enviada, entregue, lida ou falhou
`grupos:ler`	Ver grupos de WhatsApp. Os grupos do número por QR code, quem está em cada um, o link de convite e as mensagens dos grupos
`grupos:gerenciar` sensível	Administrar grupos de WhatsApp. Criar grupo, pôr e tirar pessoas, trocar nome, descrição e convite, e sair do grupo
`conversas:ler`	Ler conversas. Listar e abrir conversas, ler o histórico, ver filas e atendentes
`conversas:gerenciar`	Conduzir o atendimento. Atribuir, transferir, devolver para a IA, encerrar, reabrir, notas, adiar e agendar mensagem
`campanhas:ler`	Ler campanhas e templates. Progresso, relatório e templates aprovados
`campanhas:gerenciar` sensível	Criar e controlar campanhas. Criar disparo, iniciar, pausar e cancelar
`publicacoes:ler`	Ler publicações. Situação de cada post e onde dá para publicar
`publicacoes:publicar` sensível	Publicar no Instagram e no Status. Subir mídia, publicar agora, agendar e cancelar
`agenda:ler`	Ler a agenda. Compromissos, horários livres e o expediente da equipe
`agenda:gerenciar`	Marcar e remarcar. Marcar, remarcar, cancelar e dar baixa em compromissos
`tarefas:ler`	Ler tarefas. Listar tarefas e os tipos
`tarefas:gerenciar`	Criar e concluir tarefas. Criar, editar, concluir e cancelar
`relatorios:ler`	Ler relatórios (BI). Os mesmos conjuntos do Power BI. Colunas pessoais só com "Ver CPF e dados pessoais"
`ligacoes:ler`	Ler ligações. Desfecho, duração e resultado de cada ligação
`ligacoes:fazer` sensível	Fazer ligações com IA. A IA liga pelo WhatsApp ou pelo telefone (VoIP). Cada ligação custa minuto
`webhooks:gerenciar` sensível	Gerenciar webhooks. Cadastrar os endereços que recebem os avisos. Cada aviso pede também a permissão de ler o assunto dele
`usuarios:ler`	Ver usuários e equipes. A equipe com perfil, filas, equipes e presença. O telefone só aparece com "Ver CPF e dados pessoais"
`usuarios:gerenciar` sensível	Cadastrar e ajustar usuários. Criar atendente (convite por e-mail), editar, trocar filas, desativar e reativar. Administradores e a pessoa dona da chave não se alteram pela API
`usuarios:acesso` sensível	Mudar perfil, e-mail e senha. Dar outro perfil (nunca administrador), trocar o e-mail e mandar o e-mail de redefinir senha
`equipes:gerenciar`	Organizar equipes. Criar, renomear, ligar e desligar equipes; pôr e tirar pessoas. A equipe decide a distribuição de clientes
`filas:gerenciar` sensível	Configurar filas. Criar, editar, ligar, desligar e excluir filas (departamentos): IA, fluxo, horário e quem atende

Conceitos

Achar o cliente

Onde aparece {ref}, use ext:<código do seu sistema>, tel:<telefone com DDD>, cpf:<cpf> (exige dados-pessoais:ler) ou o id do CRM. Grave o seu código em codigoExterno ao criar o cliente e nunca mais precise do id do CRM.

Listas e páginas

As listas devolvem { "itens": [...], "proximo": "…" }. Para a página seguinte, repita o pedido com cursor=<proximo>; quando proximo vier nulo, acabou. limite controla o tamanho da página.

Repetir sem duplicar

Nas rotas que fazem alguma coisa (marcadas repetível), mande Idempotency-Key: <um código único por operação>. Se a rede cair e você repetir o mesmo pedido com a mesma chave, o CRM devolve a mesma resposta e não faz de novo — vale por 24 horas.

Datas e horários

Sempre ISO 8601 com fuso: 2026-09-26T14:00:00-03:00. Horário sem fuso é recusado onde a hora importa (agenda, adiar, agendar mensagem). A agenda aceita também data + hora no horário de São Paulo.

Dados pessoais

CPF, telefone completo das ligações, colunas pessoais dos relatórios, transcrição e gravação das ligações só existem na resposta quando a chave leva dados-pessoais:ler. Sem ela, o campo não vem nem mascarado: ele não vem.

Erros

Sempre no mesmo formato, com a mensagem em português e um codigo estável — compare o código, não o texto:

{ "erro": { "codigo": "escopo_insuficiente", "mensagem": "Esta chave não tem a permissão \"clientes:escrever\".", "detalhes": { "escopo": "clientes:escrever" } } }

HTTP	Códigos	Quando
401	`chave_ausente · chave_invalida · chave_revogada · chave_vencida`	Sem chave, chave errada, revogada ou vencida.
403	`escopo_insuficiente`	A chave não leva a permissão que a rota pede — veja `detalhes.escopo`.
403	`sem_permissao`	O perfil da pessoa dona da chave não pode fazer isto no CRM.
403	`modulo_nao_contratado`	O plano da empresa não inclui o módulo desta rota.
403	`ip_nao_permitido`	A chave está presa a outra lista de IPs.
404	`nao_encontrado`	Não existe — ou está fora do que a chave enxerga (a resposta é a mesma, de propósito).
409	`conflito · ja_assumida · ja_encerrada · horario_ocupado`	O estado mudou, ou já está como você pediu.
422	`pedido_invalido · fora_da_janela · nao_perturbe · envio_recusado`	A regra do negócio recusou; a mensagem diz o motivo.
429	`ritmo_excedido · teto_de_envio · teto_de_ligacoes`	Limite atingido — espere o cabeçalho `Retry-After`.

Erro 5xx não expõe detalhe: mande ao suporte o X-Pedido-Id da resposta.

Limites

O quê	Limite
Pedidos por chave	120 por minuto
Pedidos por empresa	600 por minuto
Mensagens (avulsa e resposta em conversa, um teto só)	30 por minuto e 1.000 por dia — para volume, use campanhas
Ligações com IA	10 por minuto e 200 por dia
Pedidos MCP	300 por minuto por chave

Toda resposta traz X-Ritmo-Limite e X-Ritmo-Restante; acima do limite vem 429 com Retry-After (segundos). Rotas de módulos contratados à parte (campanhas, cadastro de etiquetas, agenda, relatórios, ligações) respondem 403 modulo_nao_contratado quando o plano da empresa não inclui o módulo.

Avisos (webhooks)

Cadastre um endereço https público do seu sistema (em API e Webhooks ou por POST /webhooks) e escolha os avisos. Cada aviso é um POST com este corpo:

{ "id": "evt_…", "tipo": "mensagem.recebida", "criadoEm": "2026-09-25T12:00:00.000Z", "empresa": "…", "dados": { … } }

Cabeçalhos: X-InstaCRM-Evento, X-InstaCRM-Entrega e X-InstaCRM-Assinatura: t=<unix>,v1=<hex>.
Responda 2xx em até 10 segundos. Outra resposta, ou demora, é nova tentativa: 1 min, 5 min, 15 min, 1 h, 3 h, 6 h e 12 h. Cinquenta falhas seguidas desligam o endereço (religue no CRM).
O mesmo aviso pode chegar duas vezes: use o id para descartar o repetido.

Conferir a assinatura

v1 é o HMAC-SHA256, em hexadecimal, de "<t>.<corpo exato recebido>" com o segredo do webhook (mostrado uma vez, ao cadastrar). Recuse o que não bater e o que tiver mais de 5 minutos.

Node.js

import crypto from 'node:crypto';

// corpoCru: o corpo EXATO recebido (texto), antes de qualquer JSON.parse
function avisoValido(corpoCru, cabecalho, segredo) {
  const p = Object.fromEntries(String(cabecalho || '').split(',').map((x) => x.split('=')));
  const t = Number(p.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // mais de 5 min: recuse
  const esperado = crypto.createHmac('sha256', segredo).update(`${t}.${corpoCru}`).digest('hex');
  return typeof p.v1 === 'string' && p.v1.length === esperado.length
    && crypto.timingSafeEqual(Buffer.from(p.v1), Buffer.from(esperado));
}

PHP

<?php
function aviso_valido(string $corpo, string $cabecalho, string $segredo): bool {
    parse_str(str_replace(',', '&', $cabecalho), $p);
    $t = (int)($p['t'] ?? 0);
    if (!$t || abs(time() - $t) > 300) return false;
    $esperado = hash_hmac('sha256', $t . '.' . $corpo, $segredo);
    return hash_equals($esperado, (string)($p['v1'] ?? ''));
}
$corpo = file_get_contents('php://input');
$ok = aviso_valido($corpo, $_SERVER['HTTP_X_INSTACRM_ASSINATURA'] ?? '', getenv('INSTACRM_SEGREDO'));

Python

import hashlib, hmac, time

def aviso_valido(corpo: bytes, cabecalho: str, segredo: str) -> bool:
    p = dict(x.split("=", 1) for x in cabecalho.split(",") if "=" in x)
    t = int(p.get("t", 0) or 0)
    if not t or abs(time.time() - t) > 300:
        return False
    esperado = hmac.new(segredo.encode(), f"{t}.".encode() + corpo, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, p.get("v1", ""))

Os avisos

Aviso	Quando
`mensagem.recebida`	Mensagem recebida. Cada mensagem que o cliente manda (fora de grupo): o texto, o id, o arquivo para baixar e o botão, a opção de lista ou o voto de enquete que ele tocou
`mensagem.status`	Situação da mensagem. Entregue, lida ou falhou (mensagens enviadas pela API)
`cliente.criado`	Cliente criado. Cliente novo cadastrado pela API
`cliente.etapa_alterada`	Cliente mudou de etapa. Venha de onde vier: funil, etiqueta, gatilho, fluxo, IA, lote, CLT, FGTS ou API (o campo "origem" diz qual)
`etiqueta.aplicada`	Etiqueta aplicada. Por quem quer que seja: tela, IA, fluxo, FGTS ou API
`etiqueta.removida`	Etiqueta removida. Tirada pela tela, pelo fluxo ou pela API
`conversa.transferida`	Conversa transferida. Mudou de fila ou de atendente: pela tela, pela IA, na troca de agente ou pela API
`conversa.encerrada`	Conversa encerrada. Pela tela, pela API, pela IA ou por inatividade
`conversa.atribuida`	Conversa atribuída. Alguém assumiu a conversa (pela tela, pela API, pela carteira ou ao responder primeiro), ou ela voltou para a IA
`conversa.reaberta`	Conversa reaberta. Um atendimento encerrado voltou a ficar aberto: pela tela, pela API ou porque o cliente escreveu
`publicacao.publicada`	Publicação no ar. O post saiu, com o link
`publicacao.falhou`	Publicação falhou. O post não saiu, com o motivo
`campanha.concluida`	Campanha concluída. O disparo terminou
`agendamento.criado`	Compromisso marcado. Pela tela, pela IA na conversa ou pela API
`agendamento.remarcado`	Compromisso remarcado. Com o horário de antes e o novo
`agendamento.confirmado`	Compromisso confirmado. Pelo cliente (botão ou resposta no WhatsApp, ou na ligação de confirmação) ou pela equipe — o campo "por" diz quem
`agendamento.cancelado`	Compromisso cancelado. Com o motivo
`agendamento.concluido`	Compromisso concluído. Realizado ou falta
`tarefa.criada`	Tarefa criada. Pela equipe, pela API ou automática
`tarefa.concluida`	Tarefa concluída. Dada por feita
`tarefa.cancelada`	Tarefa cancelada. Não precisa mais
`ligacao.encerrada`	Ligação encerrada. Desfecho, duração e resultado da ligação com IA
`conversa.criada`	Conversa nova. Pelo cliente, pelo celular da empresa, por um atendente, pela API, pelo webchat, pela ligação ou pelo endereço da fila (o campo "origem" diz qual)
`conversa.ia_pausada`	IA pausada na conversa. Pela tela, pela API, pelo fluxo ou pela própria IA (o cliente pediu uma pessoa)
`conversa.ia_retomada`	IA retomada na conversa. A IA voltou a responder nesta conversa (pela tela ou pela API)
`pesquisa.respondida`	Pesquisa respondida. A nota (1 a 5) e o comentário da pesquisa de satisfação
`mensagem.enviada`	Mensagem enviada. Cada mensagem que sai para o cliente (atendente, IA, API, sistema), com o texto. Sem nota interna e sem grupo
`cliente.atualizado`	Cliente atualizado. O cadastro mudou (nome, telefone, e-mail, etiquetas…), com a lista do que mudou
`cliente.excluido`	Cliente excluído. Apagado de vez, pela tela ou pela API
`cliente.descadastrado`	Cliente pediu para sair. Pediu para não ser mais chamado (na ligação) ou saiu da lista de e-mail
`campanha.iniciada`	Campanha iniciada. O disparo começou
`campanha.pausada`	Campanha pausada. Pela tela, pela API, pela chave geral das automações ou pelo teto diário
`campanha.retomada`	Campanha retomada. O disparo pausado voltou a sair
`campanha.cancelada`	Campanha cancelada. O disparo parou de vez
`campanha.respondida`	Campanha respondida. O cliente respondeu a um disparo (só os ids e os horários)
`canal.conectado`	Canal conectado. O WhatsApp por QR conectou (ou voltou a conectar)
`canal.desconectado`	Canal desconectado. O WhatsApp por QR caiu ou foi desconectado, ou o token do número oficial não renovou
`canal.restrito`	Canal restrito. Número banido, ou travado pelo disjuntor da API oficial (com o motivo e até quando)
`tarefa.atualizada`	Tarefa atualizada. Mudou o título, o prazo, o tipo ou o responsável — com a lista do que mudou
`agendamento.lembrete_enviado`	Lembrete enviado. O lembrete do compromisso saiu para o cliente
`publicacao.agendada`	Publicação agendada. Entrou na fila (ou mudou de hora), pela tela, pela API ou pela IA
`publicacao.cancelada`	Publicação cancelada. Saiu da fila antes de publicar
`grupo.mensagem_recebida`	Mensagem em grupo. Cada mensagem num grupo de WhatsApp (QR code), com o grupo e quem escreveu. Separado de "mensagem recebida" para robô de resposta não responder em grupo sem ter pedido

IA (MCP)

O CRM também fala MCP, o protocolo com que assistentes de IA (Claude, Cursor, o agente de IA do n8n) usam ferramentas. Cada rota desta API vira uma ferramenta, com a mesma chave e as mesmas travas: a IA só vê o que a chave permite, e cada chamada fica registrada. Endereço: https://app.nossoia.com/api/mcp, com o mesmo cabeçalho Authorization.

Claude Code

claude mcp add --transport http instacrm https://app.nossoia.com/api/mcp \
  --header "Authorization: Bearer icrm_live_…"

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "instacrm": {
      "url": "https://app.nossoia.com/api/mcp",
      "headers": {
        "Authorization": "Bearer icrm_live_…"
      }
    }
  }
}

Claude Desktop e outros aplicativos

{
  "mcpServers": {
    "instacrm": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.nossoia.com/api/mcp",
        "--header",
        "Authorization:${ICRM_CHAVE}"
      ],
      "env": {
        "ICRM_CHAVE": "Bearer icrm_live_…"
      }
    }
  }
}

No n8n, nó MCP Client Tool: Endpoint = o endereço acima, Server Transport = HTTP Streamable, Authentication = Header Auth (nome Authorization, valor Bearer icrm_live_…).

n8n, Make e Zapier

Chamar o CRM: o nó/módulo HTTP de cada ferramenta, com o cabeçalho Authorization: Bearer <chave>. A especificação OpenAPI importa no Postman, no Insomnia e em qualquer gerador de cliente.
Receber os avisos: o gatilho de webhook da ferramenta (a URL que ela der) cadastrado como endereço de aviso.
Com IA: o MCP, acima.

Conta

Quem é a chave, as conexões da empresa e esta especificação.

GET/eu

Quem é esta chave

qualquer chave

Empresa, permissões da chave, em nome de quem ela age e os limites de ritmo. Bom para testar a chave.

curl -X GET 'https://app.nossoia.com/api/v1/eu' \
  -H 'Authorization: Bearer icrm_live_…'

GET/openapi.json

Especificação OpenAPI

qualquer chave

Esta API inteira em OpenAPI 3.1 — rotas, permissões, exemplos, erros e os avisos (webhooks). Importe no Postman, no Insomnia ou no nó HTTP do n8n.

curl -X GET 'https://app.nossoia.com/api/v1/openapi.json' \
  -H 'Authorization: Bearer icrm_live_…'

GET/canais

Conexões da empresa

qualquer chave

Lista as conexões (WhatsApp oficial, WhatsApp por QR, Instagram…) com o número de cada uma — o "canal" que as outras rotas pedem. Cada canal diz também a "situacao" de agora: QR = conectado, desconectado ou desconhecido; oficial = ok, limitado (só marketing travado) ou travado, com "motivo" e "ate".

curl -X GET 'https://app.nossoia.com/api/v1/canais' \
  -H 'Authorization: Bearer icrm_live_…'

Clientes

Cadastro de clientes (leads): criar, atualizar pelo código do seu sistema, buscar e mover no funil.

POST/clientes

Criar ou atualizar cliente

permissão: clientes:escrever repetível (Idempotency-Key)

Acha o cliente pelo codigoExterno, depois CPF, depois telefone. Se achar, atualiza só os campos enviados; se não, cria. Responde 201 quando cria e 200 quando atualiza. O cliente criado fica FORA do robô de consulta de crédito, a menos que venha "consultar": true com o CPF.

Exemplo de corpo:

{
  "nome": "Maria Souza",
  "telefone": "62999998888",
  "codigoExterno": "ERP-1042",
  "email": "maria@exemplo.com",
  "etapa": "novos",
  "camposExtras": {
    "plano": "ouro"
  }
}

curl -X POST 'https://app.nossoia.com/api/v1/clientes' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"nome":"Maria Souza","telefone":"62999998888","codigoExterno":"ERP-1042","email":"maria@exemplo.com","etapa":"novos","camposExtras":{"plano":"ouro"}}'

POST/clientes/lote

Criar ou atualizar até 500 clientes

permissão: clientes:escrever repetível (Idempotency-Key)

Mesma regra da rota simples, um por um. A resposta traz o resultado de cada item — um item ruim não derruba os outros.

Exemplo de corpo:

{
  "clientes": [
    {
      "nome": "João",
      "telefone": "62988887777",
      "codigoExterno": "ERP-1"
    },
    {
      "nome": "Ana",
      "telefone": "62977776666",
      "codigoExterno": "ERP-2"
    }
  ]
}

curl -X POST 'https://app.nossoia.com/api/v1/clientes/lote' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"clientes":[{"nome":"João","telefone":"62988887777","codigoExterno":"ERP-1"},{"nome":"Ana","telefone":"62977776666","codigoExterno":"ERP-2"}]}'

GET/clientes

Listar clientes

permissão: clientes:ler

Filtros: etapa, etiqueta, codigoExterno, telefone, cpf (exige dados-pessoais:ler), atualizadoDesde (ISO). Ordem: atualizados mais antigos primeiro — ideal para sincronizar. Paginação por "cursor" (use o "proximo" da página anterior); "limite" até 200.

Na busca (?)	Tipo	O que é
`etapa`	texto	Código da etapa do funil (veja GET /v1/funil/etapas)
`etiqueta`	texto	Nome exato de uma etiqueta
`codigoExterno`	texto	O código do cliente no seu sistema
`telefone`	texto	Telefone com DDD
`cpf`	texto	CPF — exige a permissão dados-pessoais:ler
`atualizadoDesde`	data	Só os atualizados a partir deste instante (ISO)
`limite`	inteiro	Itens por página (até 200; padrão 50)
`cursor`	texto	O "proximo" da página anterior (paginação)

curl -X GET 'https://app.nossoia.com/api/v1/clientes?limite=20' \
  -H 'Authorization: Bearer icrm_live_…'

GET/clientes/{ref}

Ver um cliente

permissão: clientes:ler

:ref pode ser o id do CRM, ext:<código do ERP>, tel:<telefone> ou cpf:<cpf> (este exige dados-pessoais:ler).

No caminho	O que é
`ref`	O cliente: ext:<código do seu sistema>, tel:<telefone>, cpf:<cpf> ou o id do CRM

curl -X GET 'https://app.nossoia.com/api/v1/clientes/ext:ERP-1042' \
  -H 'Authorization: Bearer icrm_live_…'

PATCH/clientes/{ref}

Editar cliente

permissão: clientes:escrever repetível (Idempotency-Key)

Muda só os campos enviados. "camposExtras" é mesclado com o que já existe (mande "substituirCamposExtras": true para trocar tudo).

No caminho	O que é
`ref`	O cliente: ext:<código do seu sistema>, tel:<telefone>, cpf:<cpf> ou o id do CRM

Exemplo de corpo:

{
  "telefone2": "6233334444",
  "camposExtras": {
    "plano": "prata"
  }
}

curl -X PATCH 'https://app.nossoia.com/api/v1/clientes/ext:ERP-1042' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"telefone2":"6233334444","camposExtras":{"plano":"prata"}}'

DELETE/clientes/{ref}

Excluir cliente

permissão: clientes:excluir repetível (Idempotency-Key)

Apaga o cliente de vez — o mesmo "excluir" do funil, com o que a tela apaga junto. Exige a permissão "clientes:excluir" (sensível) e, no papel de quem é dono da chave, "lead:excluir". Teto: 100 por dia por empresa.

No caminho	O que é
`ref`	O cliente: ext:<código do seu sistema>, tel:<telefone>, cpf:<cpf> ou o id do CRM

curl -X DELETE 'https://app.nossoia.com/api/v1/clientes/ext:ERP-1042' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123'

POST/clientes/{ref}/etapa

Mover no funil

permissão: clientes:escrever repetível (Idempotency-Key)

Muda a etapa do funil (veja GET /v1/funil/etapas). Registra na auditoria como a tela faz.

No caminho	O que é
`ref`	O cliente: ext:<código do seu sistema>, tel:<telefone>, cpf:<cpf> ou o id do CRM

Exemplo de corpo:

{
  "etapa": "negociacao"
}

curl -X POST 'https://app.nossoia.com/api/v1/clientes/ext:ERP-1042/etapa' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"etapa":"negociacao"}'

GET/funil/etapas

Etapas do funil

permissão: clientes:ler

Os códigos e nomes das etapas, na ordem do quadro.

curl -X GET 'https://app.nossoia.com/api/v1/funil/etapas' \
  -H 'Authorization: Bearer icrm_live_…'

Etiquetas

Etiquetas no cliente — com a automação da etiqueta rodando como na tela.

GET/etiquetas

Listar etiquetas

permissão: etiquetas:ler

Todas as etiquetas da empresa, com cor, grupo e a automação de cada uma. "?ativas=true" traz só as ativas.

Na busca (?)	Tipo	O que é
`ativas`	booleano	true traz só as etiquetas ativas

curl -X GET 'https://app.nossoia.com/api/v1/etiquetas' \
  -H 'Authorization: Bearer icrm_live_…'

POST/etiquetas

Criar etiqueta

permissão: etiquetas:gerenciar plano: Etiquetas & Automações repetível (Idempotency-Key)

Cria uma etiqueta simples (sem automação). A automação se configura na tela de Etiquetas.

Exemplo de corpo:

{
  "nome": "Cliente VIP",
  "cor": "#22c55e",
  "descricao": "Compra acima de R$ 1.000"
}

curl -X POST 'https://app.nossoia.com/api/v1/etiquetas' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"nome":"Cliente VIP","cor":"#22c55e","descricao":"Compra acima de R$ 1.000"}'

PATCH/etiquetas/{etiqueta}

Editar etiqueta

permissão: etiquetas:gerenciar plano: Etiquetas & Automações repetível (Idempotency-Key)

Muda nome, cor, descrição ou se está ativa. A automação configurada na tela é mantida. :etiqueta é o id ou o nome.

No caminho	O que é
`etiqueta`	A etiqueta: id ou nome

Exemplo de corpo:

{
  "cor": "#f97316"
}

curl -X PATCH 'https://app.nossoia.com/api/v1/etiquetas/VIP' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"cor":"#f97316"}'

DELETE/etiquetas/{etiqueta}

Excluir etiqueta

permissão: etiquetas:gerenciar plano: Etiquetas & Automações repetível (Idempotency-Key)

Apaga a etiqueta do cadastro. :etiqueta é o id ou o nome.

No caminho	O que é
`etiqueta`	A etiqueta: id ou nome

curl -X DELETE 'https://app.nossoia.com/api/v1/etiquetas/VIP' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123'

POST/clientes/{ref}/etiquetas

Etiquetar um cliente

permissão: etiquetas:aplicar repetível (Idempotency-Key)

Põe a etiqueta no cliente. Se ele tem conversa, a AUTOMAÇÃO da etiqueta roda (mensagem, régua, fluxo, mudança de etapa), exatamente como na tela. Sem conversa, a etiqueta fica no cadastro e a resposta avisa que a mensagem da automação não saiu. Etiqueta de grupo substitui as irmãs.

No caminho	O que é
`ref`	O cliente: ext:<código do seu sistema>, tel:<telefone>, cpf:<cpf> ou o id do CRM

Exemplo de corpo:

{
  "etiqueta": "Cliente VIP"
}

curl -X POST 'https://app.nossoia.com/api/v1/clientes/ext:ERP-1042/etiquetas' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"etiqueta":"Cliente VIP"}'

POST/etiquetas/aplicar-em-lote

Etiquetar vários clientes

permissão: etiquetas:aplicar repetível (Idempotency-Key)

A mesma etiqueta em até 200 clientes. Cada item da lista é uma referência (ext:, tel:, id).

Exemplo de corpo:

{
  "etiqueta": "Cliente VIP",
  "clientes": [
    "ext:ERP-1",
    "ext:ERP-2",
    "tel:62999998888"
  ]
}

curl -X POST 'https://app.nossoia.com/api/v1/etiquetas/aplicar-em-lote' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"etiqueta":"Cliente VIP","clientes":["ext:ERP-1","ext:ERP-2","tel:62999998888"]}'

DELETE/clientes/{ref}/etiquetas/{etiqueta}

Tirar etiqueta do cliente

permissão: etiquetas:aplicar repetível (Idempotency-Key)

Tira do cadastro e das conversas do cliente, e cancela as mensagens da régua que ainda não saíram.

No caminho	O que é
`ref`	O cliente: ext:<código do seu sistema>, tel:<telefone>, cpf:<cpf> ou o id do CRM
`etiqueta`	A etiqueta: id ou nome

curl -X DELETE 'https://app.nossoia.com/api/v1/clientes/ext:ERP-1042/etiquetas/VIP' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123'

GET/etiquetas/{etiqueta}/historico

Quem recebeu a etiqueta

permissão: etiquetas:ler

As aplicações mais recentes primeiro. Paginação: "antesDe" com o "proximo" da página anterior.

No caminho	O que é
`etiqueta`	A etiqueta: id ou nome

Na busca (?)	Tipo	O que é
`limite`	inteiro	Itens por página (até 200; padrão 50)
`antesDe`	data	O "proximo" da página anterior

curl -X GET 'https://app.nossoia.com/api/v1/etiquetas/VIP/historico?limite=20' \
  -H 'Authorization: Bearer icrm_live_…'

POST/clientes/{ref}/gatilhos/{gatilho}

Disparar um gatilho

permissão: etiquetas:aplicar repetível (Idempotency-Key)

Dispara um dos gatilhos do CRM (ex.: "pago", "recusado", "link_gerado") na conversa do cliente: as etiquetas ligadas a ele são aplicadas e o funil anda. Ex.: o ERP avisa que o pedido foi pago.

No caminho	O que é
`ref`	O cliente: ext:<código do seu sistema>, tel:<telefone>, cpf:<cpf> ou o id do CRM
`gatilho`	O gatilho (pago, recusado, link_gerado…)

curl -X POST 'https://app.nossoia.com/api/v1/clientes/ext:ERP-1042/gatilhos/pago' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{}'

Mensagens

Mensagem pelo WhatsApp, com os freios do CRM: texto, arquivo, voz, template completo, botões, lista, carrossel, localização, contato, enquete e Pix; reagir, editar e apagar.

POST/mensagens

Enviar mensagem (WhatsApp)

permissão: mensagens:enviar repetível (Idempotency-Key)

Manda UMA coisa para um cliente ("para": "ext:…") ou telefone: "texto"; "midia" ({ tipo, url https OU arquivo de POST /v1/mensagens/midias, legenda, nomeArquivo, voz: true para mensagem de voz }); "template" (o aprovado na Meta — com variáveis e, se o template tiver, cabeçalho, botões, carrossel, cupom ou código de acesso); "interativo" ({ tipo: botoes, lista, link, carrossel, pedirLocalizacao, catalogo, produtos ou pix, e os campos do tipo — os mesmos das rotas de cada um em /v1/conversas/{id}/…}); "localizacao"; "contatos"; "figurinha"; ou "enquete" (só QR code). Número oficial fora da janela de 24 h só aceita template. Respeita a lista "não perturbe" e tem teto próprio (padrão 30/min e 1.000/dia por empresa) — para volume, use campanhas. Use Idempotency-Key: pedido repetido não manda de novo.

Exemplo de corpo:

{
  "para": "ext:ERP-1042",
  "texto": "Olá, Maria! Seu pedido saiu para entrega."
}

curl -X POST 'https://app.nossoia.com/api/v1/mensagens' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"para":"ext:ERP-1042","texto":"Olá, Maria! Seu pedido saiu para entrega."}'

GET/mensagens/{id}

Situação de uma mensagem

permissão: mensagens:ler

enviada, entregue, lida ou falhou.

No caminho	O que é
`id`	O id da mensagem

curl -X GET 'https://app.nossoia.com/api/v1/mensagens/{id}' \
  -H 'Authorization: Bearer icrm_live_…'

PATCH/mensagens/{id}

Editar mensagem enviada

permissão: mensagens:enviar repetível (Idempotency-Key)

Troca o "texto" de uma mensagem de texto que a empresa mandou, até 15 minutos depois de enviada — o cliente vê "editada". Só pelo WhatsApp conectado por QR code: a API oficial da Meta, o Instagram e o Messenger não oferecem.

No caminho	O que é
`id`	O id da mensagem

Exemplo de corpo:

{
  "texto": "Correção: a entrega é amanhã, às 10h."
}

curl -X PATCH 'https://app.nossoia.com/api/v1/mensagens/{id}' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"texto":"Correção: a entrega é amanhã, às 10h."}'

DELETE/mensagens/{id}

Apagar para todos

permissão: mensagens:enviar repetível (Idempotency-Key)

O "apagar para todos" do WhatsApp numa mensagem que a empresa mandou: some do celular do cliente e fica marcada como apagada no CRM. Só pelo WhatsApp conectado por QR code, e dentro do prazo que o WhatsApp dá. Repetir não dá erro ("mudou": false).

No caminho	O que é
`id`	O id da mensagem

curl -X DELETE 'https://app.nossoia.com/api/v1/mensagens/{id}' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123'

POST/mensagens/{id}/reacao

Reagir a uma mensagem

permissão: mensagens:enviar repetível (Idempotency-Key)

Põe um "emoji" numa mensagem da conversa (do cliente ou da empresa), como o toque longo no WhatsApp. "emoji" vazio tira a reação. WhatsApp oficial e QR code.

No caminho	O que é
`id`	O id da mensagem

Exemplo de corpo:

{
  "emoji": "👍"
}

curl -X POST 'https://app.nossoia.com/api/v1/mensagens/{id}/reacao' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"emoji":"👍"}'

POST/mensagens/midias

Subir um arquivo para enviar

permissão: mensagens:enviar repetível (Idempotency-Key)

O arquivo CRU no corpo, com o Content-Type dele: JPEG, PNG, WEBP (figurinha), MP4, 3GP, OGG, MP3, M4A, AAC, AMR, PDF, DOC/DOCX, XLS/XLSX, PPT/PPTX, TXT, CSV ou ZIP, até 16 MB. "?nome=relatorio.pdf" sugere o nome do documento. Devolve o "midia" — vale 7 dias e só para esta empresa — para usar em "midia": { "arquivo": "<midia>" } em qualquer envio, ou em "figurinha".

curl -X POST 'https://app.nossoia.com/api/v1/mensagens/midias' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: video/mp4' \
  --data-binary @video.mp4

GET/numeros/{telefone}

Este número tem WhatsApp?

permissão: mensagens:enviar

"temWhatsapp": true, false ou null (não deu para saber agora — tente depois). A pergunta é feita por uma conexão por QR code ("canal" escolhe qual): a API oficial da Meta não oferece esta consulta. Cada consulta gasta a reputação do chip, por isso o teto é de 10 por minuto e 300 por dia por empresa, e a resposta pode levar alguns segundos.

No caminho	O que é
`telefone`	O telefone

Na busca (?)	Tipo	O que é
`canal`	inteiro	A conexão por QR code que faz o pedido (veja GET /v1/canais); sem ele, a primeira conectada

curl -X GET 'https://app.nossoia.com/api/v1/numeros/62999998888' \
  -H 'Authorization: Bearer icrm_live_…'

Atendimento

As conversas de todos os canais: ler, responder (com botões, lista, carrossel, localização, contato, enquete e Pix), visto e digitando, atribuir, transferir, devolver para a IA, encerrar, notas e mensagens agendadas.

GET/conversas

Listar conversas

permissão: conversas:ler

As conversas que a pessoa dona da chave enxerga no Atendimento (fila, equipe e carteira dela). Filtros: status (aguardando, atendendo, bot, fechado ou abertas), canal, conexao, fila, atendente (id, "eu" ou "nenhum"), cliente (ext:, tel:, id), telefone, grupo (true/false), atualizadaDesde (ISO). "ordem": recentes (padrão) ou antigas — com "antigas" + atualizadaDesde dá para sincronizar. Paginação por "cursor"; "limite" até 100.

Na busca (?)	Tipo	O que é
`status`	aguardando · atendendo · bot · fechado · abertas	Situação da conversa
`canal`	texto	Tipo do canal (whatsapp_official, whatsapp, instagram_official, messenger, webchat)
`conexao`	inteiro	O número da conexão (veja GET /v1/canais)
`fila`	texto	Id da fila (veja GET /v1/filas)
`atendente`	texto	Id do atendente, "eu" (quem é dono da chave) ou "nenhum"
`grupo`	booleano	true só grupos; false sem grupos
`cliente`	texto	O cliente: ext:<código do seu sistema>, tel:<telefone> ou o id do CRM
`telefone`	texto	Telefone do contato, com DDD
`atualizadaDesde`	data	Só as atualizadas a partir deste instante (ISO)
`ordem`	recentes · antigas	recentes (padrão) ou antigas
`limite`	inteiro	Itens por página (até 100; padrão 50)
`cursor`	texto	O "proximo" da página anterior (paginação)

curl -X GET 'https://app.nossoia.com/api/v1/conversas?limite=20' \
  -H 'Authorization: Bearer icrm_live_…'

GET/conversas/{id}

Abrir uma conversa

permissão: conversas:ler

Situação, canal, contato, fila, atendente, IA pausada ou não, protocolo, etiquetas, quantas não lidas, a última mensagem e as mensagens agendadas.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

curl -X GET 'https://app.nossoia.com/api/v1/conversas/{id}' \
  -H 'Authorization: Bearer icrm_live_…'

GET/conversas/{id}/mensagens

Histórico de mensagens

permissão: conversas:ler

Mais recentes primeiro (ou "ordem=antigas"). "desde" (ISO) corta o começo; "internas=false" esconde as notas internas. Mensagem com arquivo traz o endereço para baixar (GET /v1/mensagens/{id}/midia). Paginação por "cursor"; "limite" até 100.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Na busca (?)	Tipo	O que é
`desde`	data	Só as mensagens a partir deste instante (ISO)
`internas`	booleano	false esconde as notas internas
`ordem`	recentes · antigas	recentes (padrão) ou antigas
`limite`	inteiro	Itens por página (até 100; padrão 50)
`cursor`	texto	O "proximo" da página anterior (paginação)

curl -X GET 'https://app.nossoia.com/api/v1/conversas/{id}/mensagens?limite=20' \
  -H 'Authorization: Bearer icrm_live_…'

POST/conversas/{id}/mensagens

Responder na conversa (qualquer canal)

permissão: mensagens:enviar repetível (Idempotency-Key)

Manda UMA coisa pelo canal da conversa (WhatsApp oficial ou QR, Instagram, Messenger e webchat), com o corpo de POST /v1/mensagens: "texto", "midia" ({ tipo: imagem|video|audio|documento, url https OU arquivo de POST /v1/mensagens/midias, legenda, nomeArquivo, voz }), "interativo", "localizacao", "contatos", "figurinha" ou "enquete". Não assume a conversa nem pausa a IA — para isso, /atribuir. Número oficial fora da janela de 24 h só aceita template (POST /v1/mensagens). Respeita o "não perturbe" e divide o teto de envio com POST /v1/mensagens.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "texto": "Seu pedido 1042 foi despachado hoje."
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/mensagens' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"texto":"Seu pedido 1042 foi despachado hoje."}'

POST/conversas/{id}/botoes

Responder com botões

permissão: mensagens:enviar repetível (Idempotency-Key)

Texto com até 3 botões. De resposta ({ "id", "texto" até 20 letras }): o toque volta como mensagem, com o "id" (aviso mensagem.recebida, campo "resposta"). Pelo QR code também de link ({ texto, url }), de copiar ({ texto, copiar }) e de ligar ({ texto, telefone }); no Instagram e no Messenger, de resposta ou de link. "cabecalho" (texto; no número oficial também { tipo: imagem|video|documento, url }) e "rodape" são opcionais. WhatsApp oficial e QR, Instagram e Messenger.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "texto": "Posso confirmar seu pedido?",
  "botoes": [
    {
      "id": "sim",
      "texto": "Sim, confirmar"
    },
    {
      "id": "nao",
      "texto": "Ainda não"
    }
  ]
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/botoes' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"texto":"Posso confirmar seu pedido?","botoes":[{"id":"sim","texto":"Sim, confirmar"},{"id":"nao","texto":"Ainda não"}]}'

POST/conversas/{id}/lista

Responder com lista de opções

permissão: mensagens:enviar repetível (Idempotency-Key)

Texto com um botão ("botao", até 20 letras) que abre uma lista de até 10 opções ({ "id", "titulo" até 24 letras, "descricao" até 72 }), numa seção só ("opcoes") ou em várias ("secoes": [{ titulo, opcoes }]). O toque volta como mensagem, com o "id". WhatsApp oficial e QR; no Instagram e no Messenger vira respostas rápidas (título até 20 letras).

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "texto": "Escolha o horário:",
  "botao": "Ver horários",
  "opcoes": [
    {
      "id": "manha",
      "titulo": "Manhã",
      "descricao": "9h às 12h"
    },
    {
      "id": "tarde",
      "titulo": "Tarde"
    }
  ]
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/lista' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"texto":"Escolha o horário:","botao":"Ver horários","opcoes":[{"id":"manha","titulo":"Manhã","descricao":"9h às 12h"},{"id":"tarde","titulo":"Tarde"}]}'

POST/conversas/{id}/link

Responder com botão de link

permissão: mensagens:enviar repetível (Idempotency-Key)

Texto com UM botão que abre um endereço ("botao" até 20 letras, "url" https). O toque NÃO volta para o CRM: abre o site no aparelho do cliente. "cabecalho" e "rodape" opcionais. WhatsApp oficial e QR, Instagram e Messenger.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "texto": "Seu boleto está pronto.",
  "botao": "Abrir boleto",
  "url": "https://minhaloja.com.br/boleto/1042"
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/link' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"texto":"Seu boleto está pronto.","botao":"Abrir boleto","url":"https://minhaloja.com.br/boleto/1042"}'

POST/conversas/{id}/carrossel

Responder com carrossel

permissão: mensagens:enviar repetível (Idempotency-Key)

Cartões que o cliente desliza, cada um com "imagem" (https), "texto" e botões — de resposta ({ id, texto }) ou um de link ({ texto, url }). Número oficial: de 2 a 10 cartões, todos com os MESMOS botões (mesmo tipo e quantidade), texto do cartão até 160 letras ("video" no lugar de "imagem" também vale). Instagram e Messenger: de 1 a 10, cada um com "titulo" (até 80) e até 3 botões. QR code: de 2 a 10, 1 ou 2 botões; a imagem é baixada e mandada junto, e o desenho depende do aparelho do cliente.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "texto": "Veja as opções da semana:",
  "cartoes": [
    {
      "imagem": "https://minhaloja.com.br/p/1.jpg",
      "texto": "Bolsa Aurora — R$ 189",
      "botoes": [
        {
          "id": "quero_1",
          "texto": "Quero esta"
        }
      ]
    },
    {
      "imagem": "https://minhaloja.com.br/p/2.jpg",
      "texto": "Bolsa Lua — R$ 149",
      "botoes": [
        {
          "id": "quero_2",
          "texto": "Quero esta"
        }
      ]
    }
  ]
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/carrossel' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"texto":"Veja as opções da semana:","cartoes":[{"imagem":"https://minhaloja.com.br/p/1.jpg","texto":"Bolsa Aurora — R$ 189","botoes":[{"id":"quero_1","texto":"Quero esta"}]},{"imagem":"https://minhaloja.com.br/p/2.jpg","texto":"Bolsa Lua — R$ 149","botoes":[{"id":"quero_2","texto":"Quero esta"}]}]}'

POST/conversas/{id}/respostas-rapidas

Responder com respostas rápidas

permissão: mensagens:enviar repetível (Idempotency-Key)

Instagram e Messenger: texto com até 13 respostas que aparecem sobre o teclado ({ "id", "texto" até 20 letras }) e somem depois do toque. O toque volta como mensagem, com o "id". No WhatsApp, use botões ou lista.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "texto": "Qual tamanho você usa?",
  "opcoes": [
    {
      "id": "p",
      "texto": "P"
    },
    {
      "id": "m",
      "texto": "M"
    },
    {
      "id": "g",
      "texto": "G"
    }
  ]
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/respostas-rapidas' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"texto":"Qual tamanho você usa?","opcoes":[{"id":"p","texto":"P"},{"id":"m","texto":"M"},{"id":"g","texto":"G"}]}'

POST/conversas/{id}/localizacao

Mandar uma localização

permissão: mensagens:enviar repetível (Idempotency-Key)

Um ponto no mapa ("latitude" e "longitude"; "nome" e "endereco" opcionais) que abre a rota no aparelho do cliente. WhatsApp oficial e QR code.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "latitude": -16.6869,
  "longitude": -49.2648,
  "nome": "Loja Centro",
  "endereco": "Av. Goiás, 1000 — Goiânia"
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/localizacao' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"latitude":-16.6869,"longitude":-49.2648,"nome":"Loja Centro","endereco":"Av. Goiás, 1000 — Goiânia"}'

POST/conversas/{id}/pedir-localizacao

Pedir a localização do cliente

permissão: mensagens:enviar repetível (Idempotency-Key)

Texto com o botão "Enviar localização": o cliente toca e a localização dele volta como mensagem. Só no WhatsApp oficial (regra da Meta).

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "texto": "Para calcular o frete, mande sua localização tocando no botão abaixo."
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/pedir-localizacao' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"texto":"Para calcular o frete, mande sua localização tocando no botão abaixo."}'

POST/conversas/{id}/contato

Mandar cartão de contato

permissão: mensagens:enviar repetível (Idempotency-Key)

Até 10 cartões de contato ("contatos": [{ nome, telefone com DDD, empresa, email }]) — o cliente salva ou chama direto. WhatsApp oficial e QR code.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "contatos": [
    {
      "nome": "Financeiro Loja Centro",
      "telefone": "62999990000",
      "empresa": "Loja Centro"
    }
  ]
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/contato' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"contatos":[{"nome":"Financeiro Loja Centro","telefone":"62999990000","empresa":"Loja Centro"}]}'

POST/conversas/{id}/figurinha

Mandar figurinha

permissão: mensagens:enviar repetível (Idempotency-Key)

Figurinha WEBP 512×512: "url" (https) ou "arquivo" (o "midia" de POST /v1/mensagens/midias); "animada": true para a animada. WhatsApp oficial e QR code.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "url": "https://minhaloja.com.br/figurinhas/obrigado.webp"
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/figurinha' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://minhaloja.com.br/figurinhas/obrigado.webp"}'

POST/conversas/{id}/enquete

Mandar enquete

permissão: mensagens:enviar repetível (Idempotency-Key)

Enquete do WhatsApp: "pergunta" e de 2 a 12 "opcoes" (textos); "variasEscolhas": true deixa marcar mais de uma. Cada voto volta como mensagem com as opções marcadas (aviso mensagem.recebida, "resposta.formato": "enquete"). Só pelo WhatsApp conectado por QR code — a API oficial da Meta não tem enquete.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "pergunta": "Qual horário fica melhor?",
  "opcoes": [
    "Manhã",
    "Tarde",
    "Noite"
  ]
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/enquete' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"pergunta":"Qual horário fica melhor?","opcoes":["Manhã","Tarde","Noite"]}'

POST/conversas/{id}/catalogo

Mandar o catálogo

permissão: mensagens:enviar repetível (Idempotency-Key)

O catálogo da loja dentro do WhatsApp ("texto"; "produtoDaCapa" é o código do produto que vira a miniatura; "rodape" opcional). Só no número oficial com catálogo ligado na conta da Meta.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "texto": "Veja nossos produtos e peça por aqui mesmo."
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/catalogo' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"texto":"Veja nossos produtos e peça por aqui mesmo."}'

POST/conversas/{id}/produtos

Mandar produtos do catálogo

permissão: mensagens:enviar repetível (Idempotency-Key)

Um produto ("catalogo" + "produto", os códigos do catálogo da Meta) ou uma vitrine com até 30 ("catalogo", "titulo", "texto", "secoes": [{ titulo, produtos: [códigos] }], até 10 seções). Só no número oficial.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "catalogo": "<id do catálogo na Meta>",
  "titulo": "Novidades",
  "texto": "Separei estas para você:",
  "secoes": [
    {
      "titulo": "Bolsas",
      "produtos": [
        "BOLSA-AURORA",
        "BOLSA-LUA"
      ]
    }
  ]
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/produtos' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"catalogo":"<id do catálogo na Meta>","titulo":"Novidades","texto":"Separei estas para você:","secoes":[{"titulo":"Bolsas","produtos":["BOLSA-AURORA","BOLSA-LUA"]}]}'

POST/conversas/{id}/pix

Cobrar por Pix

permissão: mensagens:enviar repetível (Idempotency-Key)

Pedido com Pix: "texto", "referencia" (o código do pedido), "itens" [{ nome, valor em reais, quantidade }], "frete", "desconto" e o Pix — "codigo" (o copia e cola), "chave", "tipoChave" (CPF, CNPJ, EMAIL, PHONE ou EVP) e "recebedor". No número oficial vai a mensagem de pedido da Meta, com "Revisar e pagar"; no QR code, o texto com o total e o botão "Copiar código Pix". O CRM não confirma o pagamento: isso vem do seu banco.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "texto": "Seu pedido 1042",
  "referencia": "PED-1042",
  "itens": [
    {
      "nome": "Bolsa Aurora",
      "valor": 189.9,
      "quantidade": 1
    }
  ],
  "frete": 15,
  "codigo": "00020126…6304ABCD",
  "chave": "12345678000199",
  "tipoChave": "CNPJ",
  "recebedor": "Loja Centro"
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/pix' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"texto":"Seu pedido 1042","referencia":"PED-1042","itens":[{"nome":"Bolsa Aurora","valor":189.9,"quantidade":1}],"frete":15,"codigo":"00020126…6304ABCD","chave":"12345678000199","tipoChave":"CNPJ","recebedor":"Loja Centro"}'

POST/conversas/{id}/lida

Marcar como lida (visto)

permissão: mensagens:enviar repetível (Idempotency-Key)

Manda o "visto" ao cliente (os dois tiques azuis no WhatsApp; "visto" no Instagram e no Messenger) e marca a conversa como lida no CRM.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/lida' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/conversas/{id}/digitando

Mostrar digitando

permissão: mensagens:enviar repetível (Idempotency-Key)

"estado": digitando (padrão), gravando (só QR code: "gravando áudio…") ou parou. Some sozinho em alguns segundos ou quando a resposta sai. No número oficial, regra da Meta: ele vai junto com o "visto" da última mensagem do cliente.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "estado": "digitando"
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/digitando' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"estado":"digitando"}'

PATCH/conversas/{id}

Prioridade e leitura

permissão: conversas:gerenciar repetível (Idempotency-Key)

"prioridade": baixa, normal, alta ou urgente. "lida": true marca como lida; false, como não lida.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "prioridade": "alta"
}

curl -X PATCH 'https://app.nossoia.com/api/v1/conversas/{id}' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"prioridade":"alta"}'

POST/conversas/{id}/atribuir

Atribuir a um atendente

permissão: conversas:gerenciar repetível (Idempotency-Key)

"atendente": id da pessoa (GET /v1/atendentes) ou "eu". A conversa fica "atendendo" e a IA pausa, como no botão "Aceitar". Se outra pessoa assumiu primeiro, 409.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "atendente": "eu"
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/atribuir' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"atendente":"eu"}'

POST/conversas/{id}/devolver-para-ia

Devolver para a IA

permissão: conversas:gerenciar repetível (Idempotency-Key)

Tira o atendente, volta a conversa para "aguardando" e religa a IA nela.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/devolver-para-ia' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/conversas/{id}/transferir

Transferir

permissão: conversas:gerenciar repetível (Idempotency-Key)

Para uma "fila" (GET /v1/filas) e/ou um "atendente". "nota" vira nota interna na conversa. A IA pausa, como na tela.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "fila": "id-da-fila-financeiro",
  "nota": "Cliente quer segunda via do boleto"
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/transferir' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"fila":"id-da-fila-financeiro","nota":"Cliente quer segunda via do boleto"}'

POST/conversas/{id}/ia

Pausar ou religar a IA

permissão: conversas:gerenciar repetível (Idempotency-Key)

"pausada": true para a IA parar de responder nesta conversa; false para ela voltar. O pedido diz o estado final — repetir não desfaz.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "pausada": true
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/ia' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"pausada":true}'

POST/conversas/{id}/encerrar

Encerrar atendimento

permissão: conversas:gerenciar repetível (Idempotency-Key)

Fecha a conversa e o ticket, gera o protocolo e dispara a pesquisa de satisfação se estiver configurada ("enviarPesquisa": true força). "despedida" é mandada ao cliente antes de fechar. Já encerrada: 409.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "despedida": "Obrigado pelo contato! Qualquer coisa, é só chamar."
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/encerrar' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"despedida":"Obrigado pelo contato! Qualquer coisa, é só chamar."}'

POST/conversas/{id}/reabrir

Reabrir

permissão: conversas:gerenciar repetível (Idempotency-Key)

Volta um atendimento encerrado para "aguardando", com ticket novo.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/reabrir' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/conversas/{id}/notas

Nota interna

permissão: conversas:gerenciar repetível (Idempotency-Key)

Deixa uma nota que só a equipe vê — o cliente não recebe.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "texto": "Pagamento confirmado no ERP em 25/09."
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/notas' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"texto":"Pagamento confirmado no ERP em 25/09."}'

POST/conversas/{id}/adiar

Adiar

permissão: conversas:gerenciar repetível (Idempotency-Key)

Tira a conversa da fila até "ate" (ISO COM fuso) — ela volta sozinha. "motivo" vira nota interna.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "ate": "2026-09-26T09:00:00-03:00",
  "motivo": "Cliente pediu retorno amanhã"
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/adiar' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"ate":"2026-09-26T09:00:00-03:00","motivo":"Cliente pediu retorno amanhã"}'

DELETE/conversas/{id}/adiar

Tirar o adiamento

permissão: conversas:gerenciar repetível (Idempotency-Key)

A conversa volta para a fila agora.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

curl -X DELETE 'https://app.nossoia.com/api/v1/conversas/{id}/adiar' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123'

POST/conversas/{id}/pesquisa

Enviar pesquisa de satisfação

permissão: conversas:gerenciar repetível (Idempotency-Key)

Manda a pesquisa (nota de 1 a 5) ao cliente agora.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/pesquisa' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/conversas/{id}/mensagens-agendadas

Agendar mensagem

permissão: conversas:gerenciar repetível (Idempotency-Key)

"tipo": mensagem (sai para o cliente no horário) ou lembrete (aviso interno para a equipe). "quando": ISO COM fuso, de 30 segundos a 90 dias à frente.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

Exemplo de corpo:

{
  "texto": "Oi! Passando para lembrar do vencimento amanhã.",
  "quando": "2026-09-29T10:00:00-03:00",
  "tipo": "mensagem"
}

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/mensagens-agendadas' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"texto":"Oi! Passando para lembrar do vencimento amanhã.","quando":"2026-09-29T10:00:00-03:00","tipo":"mensagem"}'

DELETE/conversas/{id}/mensagens-agendadas/{agendada}

Cancelar mensagem agendada

permissão: conversas:gerenciar repetível (Idempotency-Key)

Só a que ainda não saiu. Já processada: 409.

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)
`agendada`	A mensagem agendada (id, em "mensagensAgendadas" de GET /v1/conversas/{id})

curl -X DELETE 'https://app.nossoia.com/api/v1/conversas/{id}/mensagens-agendadas/{agendada}' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123'

GET/mensagens/{id}/midia

Baixar o arquivo de uma mensagem

permissão: conversas:ler devolve arquivo

Devolve o arquivo (foto, áudio, vídeo, documento) guardado no CRM, com o Content-Type dele.

No caminho	O que é
`id`	O id da mensagem

curl -X GET 'https://app.nossoia.com/api/v1/mensagens/{id}/midia' \
  -H 'Authorization: Bearer icrm_live_…' \
  -o arquivo

GET/filas

Filas (departamentos)

permissão: conversas:ler

As filas da empresa, com quem atende em cada uma — para transferir.

curl -X GET 'https://app.nossoia.com/api/v1/filas' \
  -H 'Authorization: Bearer icrm_live_…'

GET/atendentes

Atendentes

permissão: conversas:ler

Quem está ativo na empresa, com o perfil e a presença (online, ausente, ocupado, offline).

curl -X GET 'https://app.nossoia.com/api/v1/atendentes' \
  -H 'Authorization: Bearer icrm_live_…'

Grupos

Grupos de WhatsApp pela conexão por QR code: listar, ver quem está, mandar mensagem, criar, pôr e tirar pessoas, convite e sair.

GET/grupos

Listar grupos

permissão: grupos:ler

Os grupos de WhatsApp de que o número participa: id, nome, descrição, quantas pessoas, se a empresa é administradora, quem pode mandar e editar, e a "conversaId" quando o grupo já tem conversa no CRM. Só pela conexão por QR code ("canal" escolhe qual).

Na busca (?)	Tipo	O que é
`canal`	inteiro	A conexão por QR code que faz o pedido (veja GET /v1/canais); sem ele, a primeira conectada

curl -X GET 'https://app.nossoia.com/api/v1/grupos' \
  -H 'Authorization: Bearer icrm_live_…'

GET/grupos/{id}

Ver um grupo

permissão: grupos:ler

O grupo com as "pessoas" ("id" no grupo, telefone quando o WhatsApp informa, administrador ou não) e o telefone do dono.

No caminho	O que é
`id`	O id

Na busca (?)	Tipo	O que é
`canal`	inteiro	A conexão por QR code que faz o pedido (veja GET /v1/canais); sem ele, a primeira conectada

curl -X GET 'https://app.nossoia.com/api/v1/grupos/{id}' \
  -H 'Authorization: Bearer icrm_live_…'

GET/grupos/{id}/convite

Link de convite

permissão: grupos:ler

O link de convite atual do grupo. A empresa precisa ser administradora dele.

No caminho	O que é
`id`	O id

Na busca (?)	Tipo	O que é
`canal`	inteiro	A conexão por QR code que faz o pedido (veja GET /v1/canais); sem ele, a primeira conectada

curl -X GET 'https://app.nossoia.com/api/v1/grupos/{id}/convite' \
  -H 'Authorization: Bearer icrm_live_…'

POST/grupos/{id}/mensagens

Mandar mensagem no grupo

permissão: mensagens:enviar repetível (Idempotency-Key)

O corpo de POST /v1/mensagens ("texto", "midia", "enquete", "localizacao", "contatos", "figurinha" ou "interativo" — botões, lista e link), no grupo. A conversa do grupo aparece no Atendimento, com a IA desligada como em todo grupo. Divide o teto de envio da API.

No caminho	O que é
`id`	O id

Exemplo de corpo:

{
  "texto": "Bom dia, pessoal! A loja abre às 9h hoje."
}

curl -X POST 'https://app.nossoia.com/api/v1/grupos/{id}/mensagens' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"texto":"Bom dia, pessoal! A loja abre às 9h hoje."}'

POST/grupos

Criar grupo

permissão: grupos:gerenciar repetível (Idempotency-Key)

"nome" (até 25 letras, limite do WhatsApp) e "participantes" (telefones com DDD, até 50). Quem está no "não perturbe" não entra (volta em "recusados"), e o WhatsApp pode recusar quem não deixa ser posto em grupo (volta com "ok": false). Até 10 grupos novos por dia: criar grupo em série é o padrão que o WhatsApp bane.

Exemplo de corpo:

{
  "nome": "Turma de outubro",
  "participantes": [
    "62999990000",
    "62988880000"
  ]
}

curl -X POST 'https://app.nossoia.com/api/v1/grupos' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"nome":"Turma de outubro","participantes":["62999990000","62988880000"]}'

POST/grupos/{id}/participantes

Pôr e tirar pessoas

permissão: grupos:gerenciar repetível (Idempotency-Key)

"acao": adicionar, remover, promover (a administrador) ou rebaixar; "participantes": telefones com DDD, até 50 — para tirar ou promover quem só aparece sem telefone, use o "id" da pessoa em GET /v1/grupos/{id}. O resultado vem por pessoa; quem não deixa ser posto em grupo volta com "ok": false (e "convidado": true quando o WhatsApp mandou o convite a ela). A empresa precisa ser administradora do grupo; o "não perturbe" vale para adicionar.

No caminho	O que é
`id`	O id

Exemplo de corpo:

{
  "acao": "adicionar",
  "participantes": [
    "62999990000"
  ]
}

curl -X POST 'https://app.nossoia.com/api/v1/grupos/{id}/participantes' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"acao":"adicionar","participantes":["62999990000"]}'

POST/grupos/{id}/convite

Trocar o link de convite

permissão: grupos:gerenciar repetível (Idempotency-Key)

Gera um link novo; o anterior para de funcionar.

No caminho	O que é
`id`	O id

curl -X POST 'https://app.nossoia.com/api/v1/grupos/{id}/convite' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{}'

PATCH/grupos/{id}

Editar grupo

permissão: grupos:gerenciar repetível (Idempotency-Key)

Muda só o que vier: "nome" (até 25 letras), "descricao", "soAdminsEnviam" (só administradores mandam mensagem) e "soAdminsEditam" (só eles mudam nome e foto). A resposta diz, campo a campo, o que o WhatsApp aceitou ("resultado").

No caminho	O que é
`id`	O id

Exemplo de corpo:

{
  "nome": "Turma de outubro — 2026",
  "soAdminsEnviam": true
}

curl -X PATCH 'https://app.nossoia.com/api/v1/grupos/{id}' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"nome":"Turma de outubro — 2026","soAdminsEnviam":true}'

POST/grupos/{id}/sair

Sair do grupo

permissão: grupos:gerenciar repetível (Idempotency-Key)

O número da empresa sai do grupo. A conversa e o histórico continuam no CRM.

No caminho	O que é
`id`	O id

curl -X POST 'https://app.nossoia.com/api/v1/grupos/{id}/sair' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{}'

Disparos

Campanhas pelo mesmo motor anti-banimento da tela.

GET/templates

Templates aprovados

permissão: campanhas:ler

Os templates aprovados de cada número oficial, com o texto e as variáveis.

curl -X GET 'https://app.nossoia.com/api/v1/templates' \
  -H 'Authorization: Bearer icrm_live_…'

POST/campanhas/previa

Contar o público

permissão: campanhas:ler plano: Campanhas

Quantos clientes o filtro alcança, antes de criar a campanha.

Exemplo de corpo:

{
  "publico": {
    "etapa": "novos",
    "etiquetas": [
      "Cliente VIP"
    ]
  }
}

curl -X POST 'https://app.nossoia.com/api/v1/campanhas/previa' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"publico":{"etapa":"novos","etiquetas":["Cliente VIP"]}}'

POST/campanhas/midias

Enviar foto ou vídeo da campanha

permissão: campanhas:gerenciar plano: Campanhas repetível (Idempotency-Key)

Corpo cru: vídeo MP4 (até 16 MB) ou foto JPEG/PNG/WEBP (até 8 MB; vira JPEG com o lado maior em até 1600 px). Ou JSON { "url": "https://…" } — o CRM baixa uma vez. Devolve o "midia" para POST /v1/campanhas.

curl -X POST 'https://app.nossoia.com/api/v1/campanhas/midias' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: video/mp4' \
  --data-binary @video.mp4

POST/campanhas

Criar campanha (disparo em massa)

permissão: campanhas:gerenciar plano: Campanhas repetível (Idempotency-Key)

Pelo mesmo motor das campanhas da tela (anti-banimento, disjuntor, intervalo, teto diário). Público por filtro ("publico") ou lista junto ("clientes", até 1.000 — cada um é criado ou atualizado). "canal": "oficial" exige template; "qr" usa "mensagem" (aceita {nome}). "midia": o nome devolvido por POST /v1/campanhas/midias, ou { "url": "https://…" } — no QR vai com a mensagem de legenda e sem botões; no oficial, vai no cabeçalho do template (que precisa ter cabeçalho de imagem ou vídeo). "iniciar": true já começa; para começar depois, "iniciarEm" (ISO com fuso) ou "dia"+"hora" (horário de São Paulo). Por QR, cada número manda no máximo uma mensagem de campanha a cada 45 a 90 s. BOTÕES: por QR, "botoes" (até 3 — { id, texto } de resposta, { texto, url }, { texto, copiar } ou { texto, telefone }) ou "lista" ({ botao, opcoes: [{ id, titulo, descricao }] }, até 10), sem mídia junto; o toque volta como mensagem, com o "id". No oficial os botões são os do template aprovado, e "template.botoes" manda os valores dos que têm parâmetro: [{ tipo: link (o fim do link dinâmico) | copiar (o cupom) | resposta (o payload), indice (a posição do botão no template, a partir de 0), valor }] — "{{1}}" no valor vira a primeira variável daquela pessoa.

Exemplo de corpo:

{
  "nome": "Aviso de entrega",
  "canal": "qr",
  "mensagem": "Oi {nome}, seu pedido chegou! Quer agendar a entrega?",
  "botoes": [
    {
      "id": "agendar",
      "texto": "Agendar"
    },
    {
      "id": "depois",
      "texto": "Depois"
    }
  ],
  "clientes": [
    {
      "nome": "Maria",
      "telefone": "62999998888",
      "codigoExterno": "ERP-1042"
    }
  ],
  "iniciarEm": "2026-10-12T14:00:00-03:00"
}

curl -X POST 'https://app.nossoia.com/api/v1/campanhas' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"nome":"Aviso de entrega","canal":"qr","mensagem":"Oi {nome}, seu pedido chegou! Quer agendar a entrega?","botoes":[{"id":"agendar","texto":"Agendar"},{"id":"depois","texto":"Depois"}],"clientes":[{"nome":"Maria","telefone":"62999998888","codigoExterno":"ERP-1042"}],"iniciarEm":"2026-10-12T14:00:00-03:00"}'

GET/campanhas

Listar campanhas

permissão: campanhas:ler plano: Campanhas

As mais recentes primeiro.

Na busca (?)	Tipo	O que é
`limite`	inteiro	Itens por página (até 100; padrão 20)

curl -X GET 'https://app.nossoia.com/api/v1/campanhas?limite=20' \
  -H 'Authorization: Bearer icrm_live_…'

GET/campanhas/{id}

Progresso da campanha

permissão: campanhas:ler plano: Campanhas

Status, total, enviados, falhas e os últimos envios.

No caminho	O que é
`id`	O id da campanha

curl -X GET 'https://app.nossoia.com/api/v1/campanhas/{id}' \
  -H 'Authorization: Bearer icrm_live_…'

POST/campanhas/{id}/{acao}

Iniciar, pausar, retomar, cancelar ou desagendar

permissão: campanhas:gerenciar plano: Campanhas repetível (Idempotency-Key)

:acao é iniciar, pausar, retomar, cancelar ou desagendar. Numa campanha agendada, "iniciar" começa agora e "desagendar" a devolve a rascunho, sem hora.

No caminho	O que é
`id`	O id da campanha
`acao`	iniciar, pausar, retomar ou cancelar

curl -X POST 'https://app.nossoia.com/api/v1/campanhas/{id}/pausar' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{}'

Publicações

Instagram (foto, carrossel, Reels, Story) e Status do WhatsApp.

GET/publicacoes/destinos

Onde dá para publicar

permissão: publicacoes:ler plano: Publicações

As contas do Instagram e as conexões do WhatsApp (Status), com os formatos de cada uma e a cota do Instagram.

curl -X GET 'https://app.nossoia.com/api/v1/publicacoes/destinos' \
  -H 'Authorization: Bearer icrm_live_…'

POST/midias

Subir foto ou vídeo

permissão: publicacoes:publicar plano: Publicações repetível (Idempotency-Key)

Mande o ARQUIVO no corpo (Content-Type video/mp4, video/quicktime, image/jpeg, image/png ou image/webp; vídeo até 100 MB, foto até 8 MB; para o Status do WhatsApp, vídeo só MP4 até 8 MB) ou JSON { "url": "https://…" } para o CRM baixar. Devolve "midia", que vai no POST /v1/publicacoes.

curl -X POST 'https://app.nossoia.com/api/v1/midias' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: video/mp4' \
  --data-binary @video.mp4

POST/publicacoes

Publicar agora ou agendar

permissão: publicacoes:publicar plano: Publicações repetível (Idempotency-Key)

Instagram: IMAGE, CAROUSEL (2 a 10 fotos em "midias"), STORIES ou REELS. Status do WhatsApp: texto, foto ou video (vídeo só MP4 até 8 MB). Sem "quando", publica agora; com "quando" (ISO com fuso) ou "dia"+"hora" (horário de São Paulo), agenda. Passa pelo mesmo motor do /publicacoes. "legenda" é o texto do post (foto, carrossel e Reels; até 2.200 caracteres). "comentario" é o PRIMEIRO COMENTÁRIO, que sai logo depois do post; fixá-lo no topo só pelo aplicativo do Instagram (a API da Meta não fixa). O Story não aceita legenda nem comentário: texto de Story tem de estar escrito na própria imagem.

Exemplo de corpo:

{
  "destino": "instagram",
  "canal": 996001,
  "formato": "REELS",
  "midia": "0123456789abcdef0123456789abcdef.mp4",
  "legenda": "Novidade da semana!",
  "comentario": "Comente EU QUERO que te mando o link no Direct",
  "quando": "2026-09-26T18:00:00-03:00"
}

curl -X POST 'https://app.nossoia.com/api/v1/publicacoes' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"destino":"instagram","canal":996001,"formato":"REELS","midia":"0123456789abcdef0123456789abcdef.mp4","legenda":"Novidade da semana!","comentario":"Comente EU QUERO que te mando o link no Direct","quando":"2026-09-26T18:00:00-03:00"}'

POST/publicacoes/{id}/reagendar

Agendar ou reagendar publicação

permissão: publicacoes:publicar plano: Publicações repetível (Idempotency-Key)

Publicação AGENDADA: muda a data e a hora. RASCUNHO (por exemplo, o que sai de "duplicar"): agenda para valer. "quando" (ISO com fuso) ou "dia"+"hora" (horário de São Paulo).

No caminho	O que é
`id`	O id da publicação

Exemplo de corpo:

{
  "quando": "2026-09-28T10:00:00-03:00"
}

curl -X POST 'https://app.nossoia.com/api/v1/publicacoes/{id}/reagendar' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"quando":"2026-09-28T10:00:00-03:00"}'

POST/publicacoes/{id}/tentar-de-novo

Tentar de novo a publicação que falhou

permissão: publicacoes:publicar plano: Publicações repetível (Idempotency-Key)

Só para publicação com status "falhou": ela volta para a fila e sai de novo.

No caminho	O que é
`id`	O id da publicação

curl -X POST 'https://app.nossoia.com/api/v1/publicacoes/{id}/tentar-de-novo' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/publicacoes/{id}/duplicar

Duplicar publicação

permissão: publicacoes:publicar plano: Publicações repetível (Idempotency-Key)

Cria um RASCUNHO igual (formato, legenda e mídia), na mesma conta ou em outra ("canal"). O rascunho não sai sozinho: agende por POST /v1/publicacoes/{id}/reagendar.

No caminho	O que é
`id`	O id da publicação

Exemplo de corpo:

{
  "canal": 996001
}

curl -X POST 'https://app.nossoia.com/api/v1/publicacoes/{id}/duplicar' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"canal":996001}'

GET/publicacoes

Listar publicações

permissão: publicacoes:ler plano: Publicações

As mais recentes primeiro; filtro "status" (agendada, publicada, falhou…).

Na busca (?)	Tipo	O que é
`status`	texto	agendada, publicando, publicada, falhou…
`limite`	inteiro	Itens por página (até 100; padrão 20)

curl -X GET 'https://app.nossoia.com/api/v1/publicacoes?limite=20' \
  -H 'Authorization: Bearer icrm_live_…'

GET/publicacoes/{id}

Situação da publicação

permissão: publicacoes:ler plano: Publicações

agendada, publicando, publicada (com o link) ou falhou (com o motivo).

No caminho	O que é
`id`	O id da publicação

curl -X GET 'https://app.nossoia.com/api/v1/publicacoes/{id}' \
  -H 'Authorization: Bearer icrm_live_…'

DELETE/publicacoes/{id}

Cancelar publicação

permissão: publicacoes:publicar plano: Publicações repetível (Idempotency-Key)

Cancela uma publicação agendada que ainda não saiu.

No caminho	O que é
`id`	O id da publicação

curl -X DELETE 'https://app.nossoia.com/api/v1/publicacoes/{id}' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123'

Agenda

Compromissos da equipe pelas mesmas travas da tela e da IA: expediente, conflito e horário passado.

GET/agenda

Compromissos

permissão: agenda:ler plano: Agenda

A partir de "de" (AAAA-MM-DD, dia de São Paulo; padrão hoje) por "dias" (até 45). Filtros: atendente (um ou vários ids, separados por vírgula) e status (marcado, confirmado, cancelado, realizado, faltou).

Na busca (?)	Tipo	O que é
`de`	texto	Dia inicial AAAA-MM-DD, no horário de São Paulo (padrão: hoje)
`dias`	inteiro	Quantos dias a partir de "de" (até 45; padrão 7)
`atendente`	texto	Id de um ou mais atendentes, separados por vírgula
`status`	marcado · confirmado · cancelado · realizado · faltou	marcado, confirmado, cancelado, realizado ou faltou

curl -X GET 'https://app.nossoia.com/api/v1/agenda' \
  -H 'Authorization: Bearer icrm_live_…'

GET/agenda/horarios-livres

Horários livres

permissão: agenda:ler plano: Agenda

As mesmas vagas que a IA ofereceria: dentro do expediente, sem conflito, com antecedência. Com "dia" (AAAA-MM-DD), todas as vagas daquele dia — e, sem nenhuma, "proximoDia". Sem "dia", a partir de "de" (padrão hoje) por "dias" (até 14), em dias inteiros até "limite" vagas (padrão 200); com "temMais": true, peça de novo com de=<continuarDe>, sem repetir horário. "duracao" em minutos, "atendente".

Na busca (?)	Tipo	O que é
`dia`	texto	Um dia só, AAAA-MM-DD (horário de São Paulo): traz TODAS as vagas dele e, se não houver nenhuma, "proximoDia"
`de`	texto	Sem "dia": o dia inicial AAAA-MM-DD, no horário de São Paulo (padrão: hoje)
`dias`	inteiro	Sem "dia": quantos dias à frente de "de" (até 14; padrão 7)
`limite`	inteiro	Sem "dia": teto de vagas por resposta (até 1000; padrão 200). Vêm dias inteiros: o primeiro sempre completo, os seguintes enquanto couberem
`duracao`	inteiro	Duração em minutos (padrão 30)
`atendente`	texto	Id de um ou mais atendentes, separados por vírgula

curl -X GET 'https://app.nossoia.com/api/v1/agenda/horarios-livres?limite=20' \
  -H 'Authorization: Bearer icrm_live_…'

GET/agenda/equipe

Equipe e expediente

permissão: agenda:ler plano: Agenda

Quem pode receber compromisso e o expediente de cada um (dia da semana 0 = domingo).

curl -X GET 'https://app.nossoia.com/api/v1/agenda/equipe' \
  -H 'Authorization: Bearer icrm_live_…'

GET/agenda/{id}

Ver um compromisso

permissão: agenda:ler plano: Agenda

Horário (ISO e de São Paulo), atendente, cliente, contato e situação.

No caminho	O que é
`id`	O id do compromisso

curl -X GET 'https://app.nossoia.com/api/v1/agenda/{id}' \
  -H 'Authorization: Bearer icrm_live_…'

POST/agenda

Marcar compromisso

permissão: agenda:gerenciar plano: Agenda repetível (Idempotency-Key)

Pelas mesmas travas da tela e da IA: expediente, conflito e horário passado. Horário em "data" + "hora" (São Paulo) ou "inicio" (ISO com fuso). "atendente": id ou "eu". "cliente" (ext:, tel:, id) e "conversa" (id) são opcionais. Horário tomado: 409.

Exemplo de corpo:

{
  "atendente": "eu",
  "data": "2026-09-29",
  "hora": "14:00",
  "duracaoMin": 30,
  "titulo": "Assinatura do contrato",
  "cliente": "ext:ERP-1042"
}

curl -X POST 'https://app.nossoia.com/api/v1/agenda' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"atendente":"eu","data":"2026-09-29","hora":"14:00","duracaoMin":30,"titulo":"Assinatura do contrato","cliente":"ext:ERP-1042"}'

POST/agenda/{id}/remarcar

Remarcar

permissão: agenda:gerenciar plano: Agenda repetível (Idempotency-Key)

Novo horário em "data" + "hora" (São Paulo) ou "inicio" (ISO com fuso). A resposta traz o horário de antes.

No caminho	O que é
`id`	O id do compromisso

Exemplo de corpo:

{
  "data": "2026-09-30",
  "hora": "10:30"
}

curl -X POST 'https://app.nossoia.com/api/v1/agenda/{id}/remarcar' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"data":"2026-09-30","hora":"10:30"}'

POST/agenda/{id}/cancelar

Cancelar

permissão: agenda:gerenciar plano: Agenda repetível (Idempotency-Key)

Com "motivo" opcional.

No caminho	O que é
`id`	O id do compromisso

Exemplo de corpo:

{
  "motivo": "Cliente remarcou por telefone"
}

curl -X POST 'https://app.nossoia.com/api/v1/agenda/{id}/cancelar' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"motivo":"Cliente remarcou por telefone"}'

POST/agenda/{id}/concluir

Dar baixa

permissão: agenda:gerenciar plano: Agenda repetível (Idempotency-Key)

"compareceu": true (realizado) ou false (faltou).

No caminho	O que é
`id`	O id do compromisso

Exemplo de corpo:

{
  "compareceu": true
}

curl -X POST 'https://app.nossoia.com/api/v1/agenda/{id}/concluir' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"compareceu":true}'

Tarefas

A próxima ação sobre um cliente: criar, remarcar, concluir.

GET/tarefas

Listar tarefas

permissão: tarefas:ler

Filtros: status (aberta, concluida, cancelada), tipo, responsavel (id ou "eu"), cliente (ext:, tel:, id), prazoDesde e prazoAte (ISO). Abertas vêm por prazo mais próximo; fechadas, pelas mais recentes. Paginação por "cursor"; "limite" até 100.

Na busca (?)	Tipo	O que é
`status`	aberta · concluida · cancelada	aberta, concluida ou cancelada
`tipo`	texto	Código do tipo (veja GET /v1/tarefas/tipos)
`responsavel`	texto	Id do responsável ou "eu"
`cliente`	texto	O cliente: ext:<código do seu sistema>, tel:<telefone> ou o id do CRM
`prazoDesde`	data	Prazo a partir deste instante (ISO)
`prazoAte`	data	Prazo até este instante (ISO)
`limite`	inteiro	Itens por página (até 100; padrão 30)
`cursor`	texto	O "proximo" da página anterior (paginação)

curl -X GET 'https://app.nossoia.com/api/v1/tarefas?limite=20' \
  -H 'Authorization: Bearer icrm_live_…'

GET/tarefas/tipos

Tipos de tarefa

permissão: tarefas:ler

Os códigos que "tipo" aceita (retorno, ligacao, whatsapp, documento, proposta, acompanhamento, geral).

curl -X GET 'https://app.nossoia.com/api/v1/tarefas/tipos' \
  -H 'Authorization: Bearer icrm_live_…'

GET/tarefas/{id}

Ver uma tarefa

permissão: tarefas:ler

Com o cliente, o responsável e se está vencida.

No caminho	O que é
`id`	O id da tarefa

curl -X GET 'https://app.nossoia.com/api/v1/tarefas/{id}' \
  -H 'Authorization: Bearer icrm_live_…'

POST/tarefas

Criar tarefa

permissão: tarefas:gerenciar repetível (Idempotency-Key)

Presa a um "cliente" (ext:, tel:, id) ou a uma "oportunidade". "prazo" é ISO com fuso; "responsavel", id ou "eu" (padrão: quem é dono da chave).

Exemplo de corpo:

{
  "cliente": "ext:ERP-1042",
  "titulo": "Ligar para confirmar a entrega",
  "tipo": "ligacao",
  "prazo": "2026-09-26T16:00:00-03:00"
}

curl -X POST 'https://app.nossoia.com/api/v1/tarefas' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"cliente":"ext:ERP-1042","titulo":"Ligar para confirmar a entrega","tipo":"ligacao","prazo":"2026-09-26T16:00:00-03:00"}'

PATCH/tarefas/{id}

Editar tarefa

permissão: tarefas:gerenciar repetível (Idempotency-Key)

Muda titulo, descricao, tipo, prazo ou responsavel. Só tarefa aberta se edita (409 se já foi concluída ou cancelada).

No caminho	O que é
`id`	O id da tarefa

Exemplo de corpo:

{
  "prazo": "2026-09-27T10:00:00-03:00"
}

curl -X PATCH 'https://app.nossoia.com/api/v1/tarefas/{id}' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"prazo":"2026-09-27T10:00:00-03:00"}'

POST/tarefas/{id}/concluir

Concluir

permissão: tarefas:gerenciar repetível (Idempotency-Key)

Repetir não erra: a resposta diz "jaEstava".

No caminho	O que é
`id`	O id da tarefa

curl -X POST 'https://app.nossoia.com/api/v1/tarefas/{id}/concluir' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/tarefas/{id}/cancelar

Cancelar

permissão: tarefas:gerenciar repetível (Idempotency-Key)

Repetir não erra: a resposta diz "jaEstava".

No caminho	O que é
`id`	O id da tarefa

curl -X POST 'https://app.nossoia.com/api/v1/tarefas/{id}/cancelar' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{}'

Relatórios (BI)

Os conjuntos do Power BI na mesma chave — para planilha, BI ou data lake.

GET/relatorios

Conjuntos disponíveis

permissão: relatorios:ler plano: Relatórios

Os mesmos conjuntos do Power BI e do painel de Relatórios (mensagens, atendimentos, leads, propostas, ligações, custo de IA, resumo diário…), com o grão de cada um e quais exigem "dados-pessoais:ler".

curl -X GET 'https://app.nossoia.com/api/v1/relatorios' \
  -H 'Authorization: Bearer icrm_live_…'

GET/relatorios/{conjunto}

Linhas de um conjunto

permissão: relatorios:ler plano: Relatórios

Janela por "desde" e "ate" (ISO), paginação por "cursor" (o "proximo" da página anterior; nulo = acabou), "limite" até 10.000. Instantes em UTC; colunas *_brt já no dia de São Paulo. Nome, CPF e telefone só aparecem com "dados-pessoais:ler".

No caminho	O que é
`conjunto`	O conjunto (veja GET /v1/relatorios)

Na busca (?)	Tipo	O que é
`desde`	data	Início da janela (ISO; data ou data e hora)
`ate`	data	Fim da janela (ISO)
`limite`	inteiro	Itens por página (até 10000; padrão 1000)
`cursor`	texto	O "proximo" da página anterior (paginação)

curl -X GET 'https://app.nossoia.com/api/v1/relatorios/leads?limite=20' \
  -H 'Authorization: Bearer icrm_live_…'

Ligações

Ligações com IA pelo WhatsApp e pelo telefone (VoIP), e o que aconteceu em cada uma.

GET/ligacoes

Listar ligações

permissão: ligacoes:ler plano: Ligações VOIP ou Ligações WhatsApp

Das mais recentes para trás. Filtros: desde, ate (ISO), canal (voip, whatsapp), desfecho (ATENDIDA, NAO_ATENDEU, CAIXA_POSTAL, OCUPADO…), resultado (ou SEM_SINAL), cliente. O telefone vem mascarado, a não ser com "dados-pessoais:ler" e o perfil que pode exportar ligações.

Na busca (?)	Tipo	O que é
`desde`	data	A partir deste instante (ISO)
`ate`	data	Até este instante (ISO)
`canal`	voip · whatsapp	voip ou whatsapp
`desfecho`	texto	ATENDIDA, NAO_ATENDEU, CAIXA_POSTAL, OCUPADO, NUMERO_INVALIDO, FALHA…
`resultado`	texto	O resultado da conversa, ou SEM_SINAL
`cliente`	texto	O cliente: ext:<código do seu sistema>, tel:<telefone> ou o id do CRM
`limite`	inteiro	Itens por página (até 200; padrão 50)
`cursor`	texto	O "proximo" da página anterior (paginação)

curl -X GET 'https://app.nossoia.com/api/v1/ligacoes?limite=20' \
  -H 'Authorization: Bearer icrm_live_…'

GET/ligacoes/{id}

Ver uma ligação

permissão: ligacoes:ler plano: Ligações VOIP ou Ligações WhatsApp

Desfecho, resultado da conversa, duração, custo e, com "dados-pessoais:ler", a transcrição.

No caminho	O que é
`id`	O id da ligação (veja GET /v1/ligacoes)

curl -X GET 'https://app.nossoia.com/api/v1/ligacoes/{id}' \
  -H 'Authorization: Bearer icrm_live_…'

GET/ligacoes/{id}/gravacao

Baixar a gravação

permissão: ligacoes:ler plano: Ligações VOIP ou Ligações WhatsApp devolve arquivo

O áudio da ligação (WAV). Sai com as duas vozes misturadas, para ouvir; "estereo=true" devolve o original, cliente à esquerda e IA à direita. É a voz do cliente: exige "dados-pessoais:ler" e o perfil que ouve gravação na tela. Ligação não gravada: 404 sem_gravacao.

No caminho	O que é
`id`	O id da ligação (veja GET /v1/ligacoes)

Na busca (?)	Tipo	O que é
`estereo`	booleano	true devolve os dois canais separados (cliente à esquerda, IA à direita); padrão: mono

curl -X GET 'https://app.nossoia.com/api/v1/ligacoes/{id}/gravacao' \
  -H 'Authorization: Bearer icrm_live_…' \
  -o arquivo

POST/conversas/{id}/ligar

Ligar pelo WhatsApp (IA)

permissão: ligacoes:fazer plano: Ligações WhatsApp repetível (Idempotency-Key)

A IA de voz liga para o contato desta conversa pelo WhatsApp — a mesma ligação do botão do chat, com o agente, a voz e o roteiro configurados. Exige o módulo de ligações por WhatsApp. Teto próprio (padrão 10/min e 200/dia).

No caminho	O que é
`id`	O id da conversa (veja GET /v1/conversas)

curl -X POST 'https://app.nossoia.com/api/v1/conversas/{id}/ligar' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/clientes/{ref}/ligar

Ligar para o cliente (VoIP ou WhatsApp)

permissão: ligacoes:fazer plano: Ligações VOIP ou Ligações WhatsApp repetível (Idempotency-Key)

"canal": voip (padrão — o "rediscar" do discador, com o roteiro dele e as travas de não ligar, não perturbe e teto de tentativas) ou whatsapp (pela última conversa de WhatsApp do cliente). A resposta traz o "ligacaoId"; o desfecho chega pelo aviso ligacao.encerrada ou em GET /v1/ligacoes/{id}.

No caminho	O que é
`ref`	O cliente: ext:<código do seu sistema>, tel:<telefone>, cpf:<cpf> ou o id do CRM

Exemplo de corpo:

{
  "canal": "voip"
}

curl -X POST 'https://app.nossoia.com/api/v1/clientes/ext:ERP-1042/ligar' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"canal":"voip"}'

Administração

Usuários, equipes e filas. Administrador e a pessoa dona da chave não se alteram por aqui, e a API não define senha: manda o convite.

GET/usuarios

Usuários

permissão: usuarios:ler

A equipe da empresa: perfil, se está ativo, filas, equipes, canais e telas bloqueadas, e a presença. O telefone só vem com "dados-pessoais:ler". Até 500.

Na busca (?)	Tipo	O que é
`ativos`	booleano	true: só quem está ativo; false: só os desativados; sem ele, todos

curl -X GET 'https://app.nossoia.com/api/v1/usuarios' \
  -H 'Authorization: Bearer icrm_live_…'

GET/usuarios/{id}

Ver um usuário

permissão: usuarios:ler

O mesmo de GET /v1/usuarios, de uma pessoa.

No caminho	O que é
`id`	O id do usuário (veja GET /v1/usuarios)

curl -X GET 'https://app.nossoia.com/api/v1/usuarios/{id}' \
  -H 'Authorization: Bearer icrm_live_…'

POST/usuarios

Criar usuário

permissão: usuarios:gerenciar repetível (Idempotency-Key)

Cria a pessoa e manda o convite: o e-mail de escolher senha (a API nunca define senha; "convidar": false não manda). "perfil" padrão: atendente; atendente e operador bastam "usuarios:gerenciar", qualquer outro pede "usuarios:acesso", e administrador não se cria pela API. Ocupa uma vaga do plano: sem vaga, 409 limite_do_plano. "filas" (GET /v1/filas), "canaisPermitidos" (o "canal" de GET /v1/canais; vazio = todos) e "telasBloqueadas" são conferidos antes de gravar. Só administrador ou gestor.

Exemplo de corpo:

{
  "nome": "Ana Lima",
  "email": "ana@empresa.com.br",
  "perfil": "atendente",
  "filas": [
    "<id da fila>"
  ],
  "maxAtendimentos": 5
}

curl -X POST 'https://app.nossoia.com/api/v1/usuarios' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"nome":"Ana Lima","email":"ana@empresa.com.br","perfil":"atendente","filas":["<id da fila>"],"maxAtendimentos":5}'

PATCH/usuarios/{id}

Editar usuário

permissão: usuarios:gerenciar repetível (Idempotency-Key)

Muda só o que vier; o resto do cadastro fica como está. Trocar "perfil" ou "email" pede também "usuarios:acesso". Não se alteram pela API: administradores, a pessoa dona da chave e contas de parceiro ou da plataforma (403 usuario_protegido). Quem também atende outra empresa só muda nome, telefone, cor e filas (409 conta_compartilhada). "filas" aqui é a lista completa.

No caminho	O que é
`id`	O id do usuário (veja GET /v1/usuarios)

Exemplo de corpo:

{
  "maxAtendimentos": 8,
  "veTodoOSetor": true
}

curl -X PATCH 'https://app.nossoia.com/api/v1/usuarios/{id}' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"maxAtendimentos":8,"veTodoOSetor":true}'

PUT/usuarios/{id}/filas

Filas do usuário

permissão: usuarios:gerenciar repetível (Idempotency-Key)

"filas" é a lista COMPLETA (vazia tira de todas). Para pôr ou tirar um administrador de uma fila, use PUT /v1/filas/{id}/atendentes.

No caminho	O que é
`id`	O id do usuário (veja GET /v1/usuarios)

Exemplo de corpo:

{
  "filas": [
    "<id da fila>"
  ]
}

curl -X PUT 'https://app.nossoia.com/api/v1/usuarios/{id}/filas' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"filas":["<id da fila>"]}'

POST/usuarios/{id}/desativar

Desativar usuário

permissão: usuarios:gerenciar repetível (Idempotency-Key)

Corta o acesso na hora (derruba as sessões). Repetir não desfaz: "mudou": false quando já estava desativado.

No caminho	O que é
`id`	O id do usuário (veja GET /v1/usuarios)

curl -X POST 'https://app.nossoia.com/api/v1/usuarios/{id}/desativar' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/usuarios/{id}/reativar

Reativar usuário

permissão: usuarios:gerenciar repetível (Idempotency-Key)

Ocupa de novo uma vaga do plano (sem vaga, 409 limite_do_plano). Repetir não desfaz.

No caminho	O que é
`id`	O id do usuário (veja GET /v1/usuarios)

curl -X POST 'https://app.nossoia.com/api/v1/usuarios/{id}/reativar' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/usuarios/{id}/redefinir-senha

Mandar redefinição de senha

permissão: usuarios:acesso repetível (Idempotency-Key)

A pessoa recebe o e-mail para escolher uma senha nova (vale 30 minutos). A API não vê nem define senha. Responde 202.

No caminho	O que é
`id`	O id do usuário (veja GET /v1/usuarios)

curl -X POST 'https://app.nossoia.com/api/v1/usuarios/{id}/redefinir-senha' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET/equipes

Equipes

permissão: usuarios:ler

As equipes com gestor, membros (e o papel: membro ou supervisor) e quantos clientes estão na carteira de cada uma.

curl -X GET 'https://app.nossoia.com/api/v1/equipes' \
  -H 'Authorization: Bearer icrm_live_…'

POST/equipes

Criar equipe

permissão: equipes:gerenciar repetível (Idempotency-Key)

"nome" (único na empresa), "descricao" e "gestor" (id de usuário ativo). Só administrador ou gestor.

Exemplo de corpo:

{
  "nome": "Equipe Norte",
  "gestor": "<id do usuário>"
}

curl -X POST 'https://app.nossoia.com/api/v1/equipes' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"nome":"Equipe Norte","gestor":"<id do usuário>"}'

PATCH/equipes/{id}

Editar equipe

permissão: equipes:gerenciar repetível (Idempotency-Key)

Muda só o que vier: nome, descricao, gestor, ativa. Desligar não apaga: os clientes continuam marcados com a equipe.

No caminho	O que é
`id`	O id da equipe (veja GET /v1/equipes)

Exemplo de corpo:

{
  "ativa": false
}

curl -X PATCH 'https://app.nossoia.com/api/v1/equipes/{id}' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"ativa":false}'

PUT/equipes/{id}/membros/{usuario}

Pôr alguém na equipe

permissão: equipes:gerenciar repetível (Idempotency-Key)

"papel": membro (padrão) ou supervisor. Quem já está tem o papel trocado. Só usuário ativo.

No caminho	O que é
`id`	O id da equipe (veja GET /v1/equipes)
`usuario`	O usuário (id, de GET /v1/usuarios)

Exemplo de corpo:

{
  "papel": "membro"
}

curl -X PUT 'https://app.nossoia.com/api/v1/equipes/{id}/membros/{usuario}' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"papel":"membro"}'

DELETE/equipes/{id}/membros/{usuario}

Tirar alguém da equipe

permissão: equipes:gerenciar repetível (Idempotency-Key)

Os clientes da pessoa NÃO voltam junto: a resposta diz quantos continuam com ela ("clientesQueFicaramComEla").

No caminho	O que é
`id`	O id da equipe (veja GET /v1/equipes)
`usuario`	O usuário (id, de GET /v1/usuarios)

curl -X DELETE 'https://app.nossoia.com/api/v1/equipes/{id}/membros/{usuario}' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123'

GET/filas/{id}

Ver uma fila

permissão: conversas:ler

A configuração da fila: agente de IA, fluxo, mensagens, horário por dia e quem atende. O webhook da fila não sai (é credencial).

No caminho	O que é
`id`	O id da fila (veja GET /v1/filas)

curl -X GET 'https://app.nossoia.com/api/v1/filas/{id}' \
  -H 'Authorization: Bearer icrm_live_…'

POST/filas

Criar fila

permissão: filas:gerenciar repetível (Idempotency-Key)

"nome" é obrigatório. "agenteIa" (agente de mensagem desta empresa), "fluxo", "horario": { "vinteQuatroHoras", "porDia": { "1": { "on": true, "faixas": [["08:00","18:00"]] } } } (de "0", domingo, a "6", sábado) e "atendentes" (ids de usuário).

Exemplo de corpo:

{
  "nome": "Cobrança",
  "iaLigada": false,
  "atendentes": [
    "<id do usuário>"
  ]
}

curl -X POST 'https://app.nossoia.com/api/v1/filas' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"nome":"Cobrança","iaLigada":false,"atendentes":["<id do usuário>"]}'

PATCH/filas/{id}

Editar fila

permissão: filas:gerenciar repetível (Idempotency-Key)

Muda só o que vier, inclusive "ativa" (liga e desliga). O webhook da fila fica como está.

No caminho	O que é
`id`	O id da fila (veja GET /v1/filas)

Exemplo de corpo:

{
  "mensagemForaDoHorario": "Voltamos amanhã às 8h."
}

curl -X PATCH 'https://app.nossoia.com/api/v1/filas/{id}' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"mensagemForaDoHorario":"Voltamos amanhã às 8h."}'

PUT/filas/{id}/atendentes

Quem atende na fila

permissão: filas:gerenciar repetível (Idempotency-Key)

"atendentes" é a lista COMPLETA de ids de usuário (vazia tira todos).

No caminho	O que é
`id`	O id da fila (veja GET /v1/filas)

Exemplo de corpo:

{
  "atendentes": [
    "<id do usuário>"
  ]
}

curl -X PUT 'https://app.nossoia.com/api/v1/filas/{id}/atendentes' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"atendentes":["<id do usuário>"]}'

DELETE/filas/{id}

Excluir fila

permissão: filas:gerenciar repetível (Idempotency-Key)

Recusa (422) enquanto alguma conexão estiver ligada a ela.

No caminho	O que é
`id`	O id da fila (veja GET /v1/filas)

curl -X DELETE 'https://app.nossoia.com/api/v1/filas/{id}' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123'

Avisos (webhooks)

Os endereços do seu sistema que recebem os avisos assinados.

GET/webhooks

Listar webhooks

permissão: webhooks:gerenciar

Os webhooks que ESTA chave cadastrou, com os eventos de cada um. Os cadastrados na tela ou por outra chave não aparecem.

curl -X GET 'https://app.nossoia.com/api/v1/webhooks' \
  -H 'Authorization: Bearer icrm_live_…'

POST/webhooks

Cadastrar webhook

permissão: webhooks:gerenciar repetível (Idempotency-Key)

O endereço precisa ser https e público. A resposta traz o "segredo" UMA vez: ele assina cada aviso (cabeçalho X-InstaCRM-Assinatura: t=<unix>,v1=<HMAC-SHA256 de "<t>.<corpo>">). Cada aviso exige também a permissão de ler o assunto dele (ex.: "mensagem.recebida" pede "conversas:ler"; "ligacao.encerrada", "ligacoes:ler"), e a chave precisa ser de quem enxerga a operação inteira (administrador ou gestor), porque os avisos são da empresa toda. Revogar a chave desliga os webhooks dela.

Exemplo de corpo:

{
  "url": "https://meu-erp.com.br/instacrm/avisos",
  "eventos": [
    "etiqueta.aplicada",
    "mensagem.recebida"
  ],
  "descricao": "ERP da loja"
}

curl -X POST 'https://app.nossoia.com/api/v1/webhooks' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://meu-erp.com.br/instacrm/avisos","eventos":["etiqueta.aplicada","mensagem.recebida"],"descricao":"ERP da loja"}'

PATCH/webhooks/{id}

Editar webhook

permissão: webhooks:gerenciar repetível (Idempotency-Key)

Muda url, eventos, descrição ou liga/desliga um webhook desta chave. Religar zera o contador de falhas; aviso novo pede a permissão de ler o assunto dele.

No caminho	O que é
`id`	O id do webhook (veja GET /v1/webhooks)

Exemplo de corpo:

{
  "ativo": true
}

curl -X PATCH 'https://app.nossoia.com/api/v1/webhooks/{id}' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{"ativo":true}'

DELETE/webhooks/{id}

Apagar webhook

permissão: webhooks:gerenciar repetível (Idempotency-Key)

Apaga o webhook e as entregas dele.

No caminho	O que é
`id`	O id do webhook (veja GET /v1/webhooks)

curl -X DELETE 'https://app.nossoia.com/api/v1/webhooks/{id}' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123'

POST/webhooks/{id}/testar

Mandar aviso de teste

permissão: webhooks:gerenciar

Manda um aviso "teste" assinado e diz o que o endereço respondeu.

No caminho	O que é
`id`	O id do webhook (veja GET /v1/webhooks)

curl -X POST 'https://app.nossoia.com/api/v1/webhooks/{id}/testar' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/webhooks/{id}/segredo

Trocar o segredo

permissão: webhooks:gerenciar repetível (Idempotency-Key)

Gera um segredo novo (o antigo para de valer na hora) e mostra UMA vez.

No caminho	O que é
`id`	O id do webhook (veja GET /v1/webhooks)

curl -X POST 'https://app.nossoia.com/api/v1/webhooks/{id}/segredo' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET/webhooks/{id}/entregas

Entregas recentes

permissão: webhooks:gerenciar

Cada aviso, se chegou, quantas tentativas e o último erro.

No caminho	O que é
`id`	O id do webhook (veja GET /v1/webhooks)

Na busca (?)	Tipo	O que é
`limite`	inteiro	Itens por página (até 200; padrão 50)

curl -X GET 'https://app.nossoia.com/api/v1/webhooks/{id}/entregas?limite=20' \
  -H 'Authorization: Bearer icrm_live_…'

POST/webhooks/{id}/entregas/{entrega}/reenviar

Reenviar um aviso

permissão: webhooks:gerenciar repetível (Idempotency-Key)

Volta a entrega para a fila, do zero.

No caminho	O que é
`id`	O id do webhook (veja GET /v1/webhooks)
`entrega`	A entrega (id)

curl -X POST 'https://app.nossoia.com/api/v1/webhooks/{id}/entregas/{entrega}/reenviar' \
  -H 'Authorization: Bearer icrm_live_…' \
  -H 'Idempotency-Key: pedido-123' \
  -H 'Content-Type: application/json' \
  -d '{}'