Channels API: mensagens por um canal API

A Channels API conecta o chat do seu sistema (app, site, portal do cliente) ao agente de IA da BluBash. Seu servidor envia a mensagem que o usuário escreveu, a BluBash localiza ou cria o contato pelo contactIdentifier, encaminha a mensagem ao agente de IA e devolve a resposta na mesma chamada, de forma síncrona.

POST /api/v1/channels/{channelId}/messages

O canal API é apenas receptivo: a conversa sempre começa por uma mensagem enviada pelo seu sistema. As conversas desse canal são atendidas pelo agente de IA, e a resposta da API traz as mensagens do agente de IA. Não há transferência para atendente neste canal.

Antes de começar

Peça ao suporte da BluBash a configuração do canal API e o channelId correspondente.
Tenha a API Key do workspace. Veja Introdução à API →.
Configure e teste o agente de IA que vai atender o canal. Veja Testar o agente de IA →.

URL

https://api.blubash.io/api/v1/channels/{channelId}/messages

Cabeçalhos

X-API-Key: SUA_API_KEY
Content-Type: application/json
X-Idempotency-Key: chave_unica_opcional

Cabeçalho	Obrigatório	Descrição
`X-API-Key`	Sim	API Key do workspace
`Content-Type`	Sim	Sempre `application/json`
`X-Idempotency-Key`	Não	Valor único por operação. Evita mensagens duplicadas quando você repete uma requisição

Parâmetros de path

string

obrigatório

ID do canal API configurado no workspace.

Corpo da requisição

string

obrigatório

Tipo da mensagem: TEXT, IMAGE, AUDIO, VIDEO ou DOCUMENT.

string

obrigatório

Identificador único do contato no seu sistema. A BluBash usa esse valor para criar o contato na primeira mensagem e para encontrá-lo nas seguintes. Recomendamos o e-mail do usuário.

string

Nome do contato. Usado ao criar um novo contato.

object

obrigatório

Conteúdo da mensagem. O formato depende de type, conforme a tabela abaixo.

`type`	Formato de `content`	Campos
`TEXT`	`{ "text": { ... } }`	`body` (obrigatório)
`IMAGE`	`{ "image": { ... } }`	`url` (obrigatório), `caption`
`AUDIO`	`{ "audio": { ... } }`	`url` (obrigatório)
`VIDEO`	`{ "video": { ... } }`	`url` (obrigatório), `caption`
`DOCUMENT`	`{ "document": { ... } }`	`url` (obrigatório), `filename`, `caption`

Use sempre o mesmo contactIdentifier para a mesma pessoa. Valores diferentes para o mesmo usuário (por exemplo, joao@empresa.com em uma chamada e o ID interno em outra) criam contatos separados e quebram o histórico da conversa.

Exemplos de requisição

{
  "type": "TEXT",
  "contactIdentifier": "joao@empresa.com",
  "contactName": "João Souza",
  "content": {
    "text": {
      "body": "Olá, preciso de ajuda com o meu pedido."
    }
  }
}

{
  "type": "IMAGE",
  "contactIdentifier": "joao@empresa.com",
  "content": {
    "image": {
      "url": "https://example.com/foto-produto.jpg",
      "caption": "O produto chegou assim"
    }
  }
}

{
  "type": "AUDIO",
  "contactIdentifier": "joao@empresa.com",
  "content": {
    "audio": {
      "url": "https://example.com/mensagem.mp3"
    }
  }
}

{
  "type": "VIDEO",
  "contactIdentifier": "joao@empresa.com",
  "content": {
    "video": {
      "url": "https://example.com/video.mp4",
      "caption": "Vídeo do problema"
    }
  }
}

{
  "type": "DOCUMENT",
  "contactIdentifier": "joao@empresa.com",
  "content": {
    "document": {
      "url": "https://example.com/nota-fiscal.pdf",
      "filename": "nota-fiscal.pdf",
      "caption": "Nota fiscal da compra"
    }
  }
}

Exemplo de resposta

A estrutura da resposta é a mesma para todos os tipos de mensagem.

{
  "success": true,
  "contactId": "cmg5gdkb60000sb75h4yu6mam",
  "conversationId": "cmg6etn5u000dsbx2htkjot8r",
  "messageId": "cmg6zqegm0001sbw9ip35juiq",
  "conversation": {
    "status": "ACTIVE",
    "assignedToHuman": false,
    "aiAgentId": "cmdi03x0z0003sbz6ubwtdrml",
    "aiAgentName": "Aurora",
    "teamId": "0fb043a2-75f7-42d7-b542-1ffcc1f75ccf",
    "teamName": "Suporte Técnico"
  },
  "aiMessages": [
    {
      "content": {
        "text": {
          "body": "Olá, João! Claro, me passe o número do pedido que eu verifico para você."
        },
        "type": "text"
      },
      "type": "TEXT",
      "sender_type": "AI",
      "sender_name": "Aurora",
      "channel_message_id": null
    }
  ],
  "usage": {
    "credits": 1
  }
}

Campos da resposta

boolean

obrigatório

Indica se a operação foi concluída.

string

obrigatório

ID do contato criado ou encontrado pelo contactIdentifier.

string

obrigatório

ID da conversa.

string

obrigatório

ID da mensagem enviada na requisição.

object

obrigatório

Dados da conversa e da atribuição.

Mostrar Propriedades

string

Status atual da conversa, por exemplo ACTIVE.

boolean

Indica se a conversa está atribuída a um atendente.

string

ID do agente de IA que atende a conversa.

string

Nome do agente de IA.

string

ID da equipe da conversa.

string

Nome da equipe.

array

obrigatório

Mensagens de resposta do agente de IA, da mais antiga para a mais recente. É uma lista porque o agente de IA pode dividir a resposta em várias mensagens, conforme a configuração Dividir Respostas. Exiba todas, na ordem.

object

obrigatório

Consumo de créditos.

Mostrar Propriedades

number

Créditos consumidos pela requisição.

Códigos de status HTTP

Código	Descrição
`200`	Mensagem processada com sucesso
`400`	Dados inválidos na requisição ou canal não encontrado
`401`	API Key ausente ou inválida
`404`	Canal não encontrado
`500`	Erro interno do servidor

Exemplos de integração

async function sendMessage(channelId, apiKey, contactIdentifier, text) {
  const response = await fetch(
    `https://api.blubash.io/api/v1/channels/${channelId}/messages`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': apiKey,
        'X-Idempotency-Key': crypto.randomUUID()
      },
      body: JSON.stringify({
        type: 'TEXT',
        contactIdentifier,
        content: { text: { body: text } }
      })
    }
  );

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }

  return response.json();
}

const result = await sendMessage('SEU_CHANNEL_ID', process.env.BLUBASH_API_KEY, 'joao@empresa.com', 'Olá!');
for (const message of result.aiMessages) {
  console.log(message.content.text?.body);
}

import os
import uuid
import requests

def send_message(channel_id, api_key, message_data):
    url = f"https://api.blubash.io/api/v1/channels/{channel_id}/messages"
    headers = {
        "Content-Type": "application/json",
        "X-API-Key": api_key,
        "X-Idempotency-Key": str(uuid.uuid4()),
    }
    response = requests.post(url, headers=headers, json=message_data, timeout=60)
    response.raise_for_status()
    return response.json()

message_data = {
    "type": "TEXT",
    "contactIdentifier": "joao@empresa.com",
    "contactName": "João Souza",
    "content": {"text": {"body": "Olá, preciso de ajuda!"}},
}

result = send_message("SEU_CHANNEL_ID", os.environ["BLUBASH_API_KEY"], message_data)
for message in result["aiMessages"]:
    print(message["content"]["text"]["body"])

curl -X POST "https://api.blubash.io/api/v1/channels/SEU_CHANNEL_ID/messages" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_API_KEY" \
  -d '{
    "type": "TEXT",
    "contactIdentifier": "joao@empresa.com",
    "contactName": "João Souza",
    "content": {
      "text": {
        "body": "Olá, preciso de ajuda!"
      }
    }
  }'

A resposta só volta depois que o agente de IA termina de responder. Configure no seu cliente HTTP um timeout compatível e mostre um indicador de “digitando” para o usuário enquanto aguarda.

Limitações

Item	Regra
Atendimento	Apenas agente de IA. Não há transferência para atendente neste canal.
`contactIdentifier`	Use sempre o mesmo valor para a mesma pessoa. Recomendamos o e-mail.
URLs de mídia	Precisam ser públicas e acessíveis sem autenticação.
Tamanho de arquivo	Até 10 MB por arquivo.
Download de mídia	Timeout de 30 segundos.
Duplicidade	Use `X-Idempotency-Key` para evitar mensagens duplicadas em novas tentativas.

Visão geral

Endpoints

Channels API: mensagens por um canal API

Antes de começar

URL

Cabeçalhos

Parâmetros de path

Corpo da requisição

Exemplos de requisição

Exemplo de resposta

Campos da resposta

Códigos de status HTTP

Exemplos de integração

Limitações

Próximos passos

Treinar o agente de IA

Campaigns API

​Antes de começar

​URL

​Cabeçalhos

​Parâmetros de path

​Corpo da requisição

​Exemplos de requisição

​Exemplo de resposta

​Campos da resposta

​Códigos de status HTTP

​Exemplos de integração

​Limitações

​Próximos passos

Treinar o agente de IA

Campaigns API

Antes de começar

URL

Cabeçalhos

Parâmetros de path

Corpo da requisição

Exemplos de requisição

Exemplo de resposta

Campos da resposta

Códigos de status HTTP

Exemplos de integração

Limitações

Próximos passos