Pular para o conteúdo principal
A Channels API permite enviar mensagens a contatos por meio de um canal de API configurado no seu workspace. Quando você envia uma mensagem, a plataforma cria ou localiza o contato pelo contactIdentifier, roteia a mensagem para o seu agente de IA e retorna a resposta do agente de forma síncrona na mesma chamada de API.
As conversas por um canal de API são tratadas exclusivamente por agentes de IA. Não há interface para agentes humanos participarem dessas conversas, portanto, a transferência para um humano não é suportada.

​
Endpoint

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

​
Autenticação

Inclua sua Workspace API Key e, opcionalmente, uma chave de idempotência nos cabeçalhos da requisição. 
X-API-Key: your_workspace_api_key
Content-Type: application/json
X-Idempotency-Key: optional_key_to_prevent_duplicates

​
Parâmetros de path

​
channelId
string
obrigatório
O ID do canal de API configurado no seu workspace.

​
Parâmetros do corpo da requisição

​
type
string
obrigatório
O tipo de mensagem. Um de: TEXT, IMAGE, AUDIO, VIDEO, DOCUMENT.
​
contactIdentifier
string
obrigatório
Um identificador único para o contato. Usado para criar ou localizar o contato entre requisições. Recomendamos usar o endereço de e-mail do contato.
​
contactName
string
Nome de exibição do contato. Usado ao criar um novo registro de contato.
​
content
object
obrigatório
O payload da mensagem. O formato deste objeto depende do campo type — veja os exemplos de tipo de mensagem abaixo.
Use sempre o mesmo valor de contactIdentifier para a mesma pessoa. Usar identificadores diferentes para o mesmo contato (por exemplo, joao@example.com em uma requisição e user@example.com em outra) cria registros de contato separados e quebra o histórico da conversa.

​
Tipos de mensagem

​
Texto

{
  "content": {
    "text": {
      "body": "Hello, how can I help you?"
    }
  },
  "type": "TEXT",
  "contactIdentifier": "user@example.com",
  "contactName": "User Name"
}

​
Imagem

{
  "content": {
    "image": {
      "url": "https://example.com/image.jpg",
      "caption": "Image caption"
    }
  },
  "type": "IMAGE",
  "contactIdentifier": "user@example.com"
}

​
Áudio

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

​
Vídeo

{
  "content": {
    "video": {
      "url": "https://example.com/video.mp4",
      "caption": "Video caption"
    }
  },
  "type": "VIDEO",
  "contactIdentifier": "user@example.com"
}

​
Documento

{
  "content": {
    "document": {
      "url": "https://example.com/document.pdf",
      "filename": "document.pdf",
      "caption": "Document description"
    }
  },
  "type": "DOCUMENT",
  "contactIdentifier": "user@example.com"
}

​
Campos da resposta

​
success
boolean
obrigatório
Indica se a operação foi bem-sucedida.
​
contactId
string
obrigatório
O ID único do contato criado ou correspondido pelo contactIdentifier.
​
conversationId
string
obrigatório
O ID único da conversa.
​
messageId
string
obrigatório
O ID único da mensagem que foi enviada.
​
conversation
object
obrigatório
Detalhes sobre a conversa e sua atribuição.
​
aiMessages
array
obrigatório
As mensagens de resposta do agente de IA, ordenadas de forma ascendente (primeiro as mais antigas). Trata-se de um array porque a IA pode dividir sua resposta em várias mensagens sequenciais.
​
usage
object
obrigatório
Informações de consumo de créditos.

​
Códigos de status HTTP

CódigoDescrição
200Sucesso — mensagem processada
400Dados inválidos da requisição ou canal não encontrado
401Chave de API ausente ou inválida
404Canal não encontrado
500Erro interno do servidor

​
Exemplos de integração

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

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

  return await response.json();
}

try {
  const result = await sendMessage('channel_123', 'your_api_key', 'Hello!');
  console.log('Message sent:', result);
} catch (error) {
  console.error('Error:', error);
}

​
Limitações

  • Apenas IA: As conversas são exclusivas dos agentes de IA — a transferência para agente humano não está disponível.
  • contactIdentifier consistente: Use sempre o mesmo valor para o mesmo contato. Recomendamos usar o endereço de e-mail do contato.
  • URLs de mídia públicas: As URLs de imagem, áudio, vídeo e documento precisam estar acessíveis publicamente.
  • Limite de tamanho de arquivo: Máximo de 10 MB por arquivo.
  • Timeout de download: Downloads de mídia têm timeout de 30 segundos.
  • Idempotência: Use X-Idempotency-Key para evitar mensagens duplicadas em requisições reenviadas.