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

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

string

obrigatório

O ID do canal de API configurado no seu workspace.

Parâmetros do corpo da requisição

string

obrigatório

O tipo de mensagem. Um de: TEXT, IMAGE, AUDIO, VIDEO, DOCUMENT.

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.

string

Nome de exibição do contato. Usado ao criar um novo registro de contato.

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"
}

{
  "success": true,
  "contactId": "cmg5gdkb60000sb75h4yu6mam",
  "conversationId": "cmg6etn5u000dsbx2htkjot8r",
  "messageId": "cmg6zqegm0001sbw9ip35juiq",
  "conversation": {
    "status": "ACTIVE",
    "assignedToHuman": false,
    "aiAgentId": "cmdi03x0z0003sbz6ubwtdrml",
    "aiAgentName": "Aurora",
    "teamId": "0fb043a2-75f7-42d7-b542-1ffcc1f75ccf",
    "teamName": "Technical Support"
  },
  "aiMessages": [
    {
      "content": {
        "text": {
          "body": "Hello! How can I help you today?"
        },
        "type": "text"
      },
      "type": "TEXT",
      "sender_type": "AI",
      "sender_name": "Aurora",
      "channel_message_id": null
    }
  ],
  "usage": {
    "credits": 1
  }
}

Imagem

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

{
  "success": true,
  "contactId": "cmg5gdkb60000sb75h4yu6mam",
  "conversationId": "cmg6etn5u000dsbx2htkjot8r",
  "messageId": "cmg6zqegm0001sbw9ip35juiq",
  "conversation": {
    "status": "ACTIVE",
    "assignedToHuman": false,
    "aiAgentId": "cmdi03x0z0003sbz6ubwtdrml",
    "aiAgentName": "Aurora",
    "teamId": "0fb043a2-75f7-42d7-b542-1ffcc1f75ccf",
    "teamName": "Technical Support"
  },
  "aiMessages": [
    {
      "content": {
        "text": {
          "body": "I see an interesting image! How can I help you with that?"
        },
        "type": "text"
      },
      "type": "TEXT",
      "sender_type": "AI",
      "sender_name": "Aurora",
      "channel_message_id": null
    }
  ],
  "usage": {
    "credits": 1
  }
}

Áudio

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

{
  "success": true,
  "contactId": "cmg5gdkb60000sb75h4yu6mam",
  "conversationId": "cmg6etn5u000dsbx2htkjot8r",
  "messageId": "cmg6zqegm0001sbw9ip35juiq",
  "conversation": {
    "status": "ACTIVE",
    "assignedToHuman": false,
    "aiAgentId": "cmdi03x0z0003sbz6ubwtdrml",
    "aiAgentName": "Aurora",
    "teamId": "0fb043a2-75f7-42d7-b542-1ffcc1f75ccf",
    "teamName": "Technical Support"
  },
  "aiMessages": [
    {
      "content": {
        "text": {
          "body": "Audio transcription: Hello, I need help with my order"
        },
        "type": "text"
      },
      "type": "TEXT",
      "sender_type": "AI",
      "sender_name": "Aurora",
      "channel_message_id": null
    }
  ],
  "usage": {
    "credits": 1
  }
}

Vídeo

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

{
  "success": true,
  "contactId": "cmg5gdkb60000sb75h4yu6mam",
  "conversationId": "cmg6etn5u000dsbx2htkjot8r",
  "messageId": "cmg6zqegm0001sbw9ip35juiq",
  "conversation": {
    "status": "ACTIVE",
    "assignedToHuman": false,
    "aiAgentId": "cmdi03x0z0003sbz6ubwtdrml",
    "aiAgentName": "Aurora",
    "teamId": "0fb043a2-75f7-42d7-b542-1ffcc1f75ccf",
    "teamName": "Technical Support"
  },
  "aiMessages": [
    {
      "content": {
        "text": {
          "body": "I received your video! How can I help you with that?"
        },
        "type": "text"
      },
      "type": "TEXT",
      "sender_type": "AI",
      "sender_name": "Aurora",
      "channel_message_id": null
    }
  ],
  "usage": {
    "credits": 1
  }
}

Documento

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

{
  "success": true,
  "contactId": "cmg5gdkb60000sb75h4yu6mam",
  "conversationId": "cmg6etn5u000dsbx2htkjot8r",
  "messageId": "cmg6zqegm0001sbw9ip35juiq",
  "conversation": {
    "status": "ACTIVE",
    "assignedToHuman": false,
    "aiAgentId": "cmdi03x0z0003sbz6ubwtdrml",
    "aiAgentName": "Aurora",
    "teamId": "0fb043a2-75f7-42d7-b542-1ffcc1f75ccf",
    "teamName": "Technical Support"
  },
  "aiMessages": [
    {
      "content": {
        "text": {
          "body": "I received your document! How can I help you with that?"
        },
        "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 bem-sucedida.

string

obrigatório

O ID único do contato criado ou correspondido pelo contactIdentifier.

string

obrigatório

O ID único da conversa.

string

obrigatório

O ID único da mensagem que foi enviada.

object

obrigatório

Detalhes sobre a conversa e sua atribuição.

Mostrar properties

string

Status atual da conversa (por exemplo, ACTIVE).

boolean

Se a conversa está atribuída a um agente humano.

string

ID do agente de IA que está cuidando da conversa.

string

Nome de exibição do agente de IA.

string

ID da equipe à qual a conversa pertence.

string

Nome de exibição da equipe.

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.

object

obrigatório

Informações de consumo de créditos.

Mostrar properties

number

Número de créditos consumidos por esta requisição.

Códigos de status HTTP

Código	Descrição
`200`	Sucesso — mensagem processada
`400`	Dados inválidos da requisição ou canal não encontrado
`401`	Chave de API ausente ou inválida
`404`	Canal não encontrado
`500`	Erro 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);
}

import requests

def send_message(channel_id, api_key, message_data):
    url = f"https://your-domain.com/api/v1/channels/{channel_id}/messages"

    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': api_key
    }

    response = requests.post(url, headers=headers, json=message_data)

    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"HTTP {response.status_code}: {response.text}")

message_data = {
    "content": {
        "text": {
            "body": "Hello, I need help!"
        }
    },
    "type": "TEXT",
    "contactIdentifier": "customer@example.com",
    "contactName": "John Smith"
}

try:
    result = send_message('channel_123', 'your_api_key', message_data)
    print('Message sent:', result)
except Exception as e:
    print('Error:', e)

curl -X POST "https://your-domain.com/api/v1/channels/channel_123/messages" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "content": {
      "text": {
        "body": "Hello, I need help!"
      }
    },
    "type": "TEXT",
    "contactIdentifier": "customer@example.com",
    "contactName": "John Smith"
  }'

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.

Visão geral

Endpoints

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

Endpoint

Autenticação

Parâmetros de path

Parâmetros do corpo da requisição

Tipos de mensagem

Texto

Imagem

Áudio

Vídeo

Documento

Campos da resposta

Códigos de status HTTP

Exemplos de integração

Limitações

​Endpoint

​Autenticação

​Parâmetros de path

​Parâmetros do corpo da requisição

​Tipos de mensagem

​Texto

​Imagem

​Áudio

​Vídeo

​Documento

​Campos da resposta

​Códigos de status HTTP

​Exemplos de integração

​Limitações

Endpoint

Autenticação

Parâmetros de path

Parâmetros do corpo da requisição

Tipos de mensagem

Texto

Imagem

Áudio

Vídeo

Documento

Campos da resposta

Códigos de status HTTP

Exemplos de integração

Limitações