Integrar um aplicativo próprio ao Webchat (modo API)

Acesso

Caminho: Opa! Store → Webchat → Acessar → registro do canal → Integrar aplicativo próprio

Visão geral

O modo API do Webchat permite que você use o Opa! Suite como central de atendimento do chat do aplicativo da sua empresa, sem a janela de chat do site. Assim, o cliente continua dentro do seu app, e a equipe atende pelo Opa! Suite, com histórico e métricas como em qualquer outro canal.

A integração funciona por webhook nas duas direções: o seu aplicativo envia as mensagens do usuário ao Opa! Suite por HTTP, e o Opa! Suite envia para uma URL do seu aplicativo tudo o que for respondido no atendimento, seja por um atendente, pelo agente virtual ou pelo fluxo de comunicação. Não há consulta periódica (polling).

Este artigo é voltado a quem desenvolve a integração. Para instalar o chat no site, veja Instalar o Webchat no site.

Pré-requisitos

• Webchat instalado no Opa! Suite, com licença ativa e um Agente virtual responsável. Veja Instalar o Webchat no site.
• Permissão para visualizar o Opa! Store no seu grupo de permissões.
• Uma URL no seu aplicativo pronta para receber requisições POST com JSON. É para ela que o Opa! Suite envia as respostas do atendimento. Recomendamos que seja HTTPS.
• Quem desenvolve o aplicativo, com acesso para implementar as chamadas descritas aqui.

Passo a passo

Ativar o modo API no canal

1. Acesse Opa! Store → Webchat → Acessar e abra o registro do canal.
2. Na seção Integrar aplicativo próprio, clique em Editar informações.
3. Ative Integrar aplicativo próprio.
4. Em API de envio de mensagens, informe a URL do seu aplicativo que vai receber as respostas do atendimento (ex.: https://app.suaempresa.com.br/opa/webhook). O campo é obrigatório e precisa ser uma URL válida.
5. Clique em Salvar.

Copiar os dados da integração

Depois de salvar, a seção mostra três dados gerados pelo Opa! Suite, cada um com botão para copiar:

Campo na tela	Para que serve
Token de segurança	Chega no cabeçalho X-Signature de cada requisição que o Opa! Suite envia ao seu aplicativo. Serve para confirmar a origem.
API de recebimento de mensagens	Endereço base para o seu aplicativo enviar as mensagens do usuário.
Token de autenticação do Opa!	Vai no cabeçalho Authorization quando o seu aplicativo chama a API de recebimento.

1. Copie os três dados e guarde-os no servidor do seu aplicativo.
2. Anote o ID do canal. Ele aparece no endereço do navegador, na tela do canal (.../web-chat/list/ID-DO-CANAL/adjustments), e no topo da tela quando Mostrar IDs nos formulários está ativo em Configurações → Empresa.

O ID do canal faz parte da URL

Para enviar mensagens, use https://SEU-DOMINIO/api/v1/webchat/ID-DO-CANAL/message. O campo API de recebimento de mensagens mostra o endereço sem o ID do canal: inclua o ID antes de /message. Sem ele, a API responde UNAUTHORIZED.

Desativar a integração gera tokens novos

Ao desativar Integrar aplicativo próprio e salvar, os tokens são apagados. Se você ativar de novo, o Opa! Suite gera tokens diferentes, e o seu aplicativo precisa ser atualizado.

Implementar e testar

1. Implemente o envio das mensagens do usuário, conforme Enviar mensagens do usuário ao Opa! Suite.
2. Implemente o recebimento das respostas, conforme Receber as mensagens do atendimento.
3. Envie uma mensagem de teste pelo aplicativo.
4. Confira se o atendimento aparece no Opa! Suite e se a resposta chega à URL configurada.

Resultado esperado

Cada mensagem enviada pelo seu aplicativo abre ou continua um atendimento no Opa! Suite, que segue o agente virtual e o fluxo de comunicação do canal. Cada mensagem enviada nesse atendimento pelo atendente, pelo agente virtual ou pelo fluxo é entregue à URL informada em API de envio de mensagens.

Enviar mensagens do usuário ao Opa! Suite

Item	Valor
Método	POST
URL	https://SEU-DOMINIO/api/v1/webchat/ID-DO-CANAL/message
Cabeçalho de autenticação	Authorization: Bearer TOKEN-DE-AUTENTICACAO-DO-OPA
Tipo de conteúdo	Content-Type: application/json

O token precisa ser exatamente o Token de autenticação do Opa! daquele canal. Não é o token de um usuário do Opa! Suite.

Mensagem de texto

{
  "user": {
    "id": "usuario-externo-123",
    "email": "joao@exemplo.com",
    "username": "João Silva",
    "avatar": "https://exemplo.com/avatar.png"
  },
  "message": {
    "type": "text",
    "text": "Olá, preciso de ajuda"
  }
}

Mensagem com arquivo (por URL)

{
  "user": { "id": "usuario-externo-123" },
  "message": {
    "type": "media",
    "media": {
      "mediaType": "image/png",
      "url": "https://exemplo.com/comprovante.png",
      "filename": "comprovante.png",
      "caption": "Segue o comprovante"
    }
  }
}

Para enviar o arquivo dentro da própria requisição, troque url por data, com o conteúdo do arquivo em base64.

Campos

Campo	Obrigatório	Regra
user.id	Sim	Texto não vazio. Identifica o contato e a conversa (veja Identidade do contato).
user.email, user.username, user.avatar	Não	Texto. Preenchem ou atualizam o nome, o e-mail e a foto do contato no Opa! Suite. Em avatar, informe a URL da imagem.
message.type	Sim	"text" ou "media".
message.text	Sim, se type for text	Texto não vazio.
message.media.mediaType	Sim, se type for media	Tipo MIME válido (ex.: image/png, application/pdf).
message.media.url	Um dos dois	URL HTTPS válida do arquivo.
message.media.data	Um dos dois	Conteúdo do arquivo em base64 válido.
message.media.filename, message.media.caption	Não	Nome do arquivo e legenda.

Em media, informe url ou data, nunca os dois.

Exemplo com curl

curl -X POST "https://SEU-DOMINIO/api/v1/webchat/ID-DO-CANAL/message" \
  -H "Authorization: Bearer TOKEN-DE-AUTENTICACAO-DO-OPA" \
  -H "Content-Type: application/json" \
  -d '{"user":{"id":"usuario-123"},"message":{"type":"text","text":"Olá"}}'

Identidade do contato e continuidade da conversa

• O user.id identifica o contato. Enquanto o seu aplicativo enviar o mesmo user.id, o Opa! Suite reconhece o mesmo contato e mantém a continuidade entre sessões.
• No modo API, quem cria e guarda esse identificador é o seu aplicativo. Gere um valor fixo por usuário (por exemplo, um UUID) e salve do seu lado. Um user.id novo cria um contato novo.
• Os campos email, username e avatar atualizam o cadastro do contato sempre que forem enviados.

Limites de anexos

• Qualquer tipo MIME válido é aceito em mediaType, como imagens (image/*) e PDF (application/pdf).
• Quando o arquivo vai por URL, o Opa! Suite baixa o arquivo e confere se o tipo devolvido pelo servidor é da mesma família do mediaType informado (ex.: image/* com image/*). Se não for, a mensagem é recusada com Failed to process message media.
• Limite por URL: 40 MB por arquivo. Arquivos maiores ou vazios são recusados.
• Limite por base64: a requisição inteira pode ter no máximo 20 MB. Como o base64 aumenta o tamanho do arquivo, prefira enviar por URL os arquivos maiores.

Receber as mensagens do atendimento

Toda mensagem enviada no atendimento por um atendente, pelo agente virtual ou pelo fluxo de comunicação gera um POST para a URL de API de envio de mensagens.

Item	Valor
Método	POST
URL	A URL informada em API de envio de mensagens
Cabeçalhos	X-Signature: TOKEN-DE-SEGURANCA e Content-Type: application/json
Corpo	Objeto com customerService (dados do atendimento) e message (a mensagem)

Valide a origem: antes de aceitar a requisição, confira se o valor de X-Signature é igual ao Token de segurança do canal. Se for diferente, descarte.

Dados do atendimento (customerService)

Campo	Significado
_id	Identificador do atendimento no Opa! Suite.
protocolo	Protocolo do atendimento.
canal_cliente	Identificador do contato no canal, ou seja, o user.id que o seu aplicativo enviou. Use para saber a qual usuário entregar a mensagem.
id_user	Identificador do contato no Opa! Suite.

Mensagem (message)

Campo	Significado
_id	Identificador da mensagem.
id_rota	Identificador do atendimento.
id_atend	Quem enviou do lado do Opa! Suite.
id_assistant	Preenchido quando a mensagem foi gerada por um assistente de IA.
tipo	Tipo do conteúdo, como texto, midia, localizacao ou menuInterativo.
mensagem	Conteúdo da mensagem.
objeto	Anexo, quando houver, com nome, tipo, size, descricao e url para download.
data	Data e hora da mensagem.

Respostas e erros

Situação	Status HTTP	Corpo da resposta
Mensagem recebida	200	{ "success": true }
Sem o cabeçalho Authorization	401	{ "error": "UNAUTHORIZED" }
Canal inativo, URL sem o ID do canal, modo API desativado ou token de outro canal	401	{ "error": "UNAUTHORIZED" }
Campo inválido ou faltando	200	{ "error": "ARGUMENT_VALUE_ERROR", "message": "detalhe do campo" }
Canal não inicializado no momento do envio	200	{ "error": "NOT_FOUND_ERROR", "message": "Web chat channel not initialized" }
Não foi possível baixar ou validar o arquivo	200	{ "error": "BAD_REQUEST_ERROR", "message": "Failed to process message media" }
Não foi possível salvar a mensagem	200	{ "error": "BAD_REQUEST_ERROR", "message": "Failed to persist message media" }
Erro inesperado no servidor	500	Erro genérico

Trate o campo error, não só o status

Os erros de validação e de processamento voltam com status 200 e o detalhe no campo error do corpo. Só as falhas de autenticação e os erros inesperados usam status de erro. Sempre confira se o corpo tem "success": true.

Limitações do modo API

• "Digitando" e confirmação de leitura: não são enviados ao seu aplicativo, e a API não recebe esses eventos do usuário. A entrada aceita só mensagens de texto e de arquivo.
• Posição na fila e disponibilidade de atendentes: não há consulta dessas informações pela API. Para avisar o contato sobre a posição na fila, use a opção Avisar posição na fila nas configurações do departamento.
• Limite de requisições: o Opa! Suite não define um limite de requisições para esta API.
• Confirmação de recebimento: as mensagens recebidas entram numa fila de processamento. O { "success": true } confirma que a mensagem foi aceita, não que já apareceu para o atendente.

Problemas comuns

Sintoma	O que verificar
A API responde UNAUTHORIZED	Confira se a URL tem o ID do canal antes de /message, se o cabeçalho é Authorization: Bearer seguido do Token de autenticação do Opa! do mesmo canal, se Integrar aplicativo próprio está ativo e se o canal está Ativo.
A API responde NOT_FOUND_ERROR	O canal não estava disponível no momento do envio. Confira o Status do Webchat e tente de novo.
As respostas do atendente não chegam ao aplicativo	Confira a URL em API de envio de mensagens, se ela aceita POST com JSON e se o seu aplicativo não está recusando a requisição na validação do X-Signature.
Cada mensagem cria um contato novo	O user.id está mudando. Use sempre o mesmo identificador para o mesmo usuário.

Boas práticas

• Guarde os tokens no servidor do seu aplicativo, nunca no código que roda no celular ou no navegador do usuário.
• Sempre valide o X-Signature antes de processar uma mensagem recebida.
• Use um user.id estável.
• Prefira enviar arquivos por URL HTTPS.

Conteúdos relacionados

• Instalar o Webchat no site
• Configurar o agente virtual
• Fluxo de comunicação
• Departamentos
• Empresa