Canal API

Endpoint

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

Autenticação

X-API-Key: sua_workspace_api_key_aqui
Content-Type: application/json
X-Idempotency-Key: chave_opcional_para_evitar_duplicatas

Parâmetros

channelId: ID do canal API configurado no seu workspace
contactIdentifier: Obrigatório - Identificador único do contato (recomendamos usar email)

Importante sobre contactIdentifier

O contactIdentifier é usado para criar e identificar contatos. Use sempre o mesmo valor para o mesmo contato:

✅ Correto: Sempre usar user@example.com para João Silva
❌ Incorreto: Usar joao@example.com em uma mensagem e user@example.com em outra

Recomendação: Use o email como contactIdentifier para garantir que todas as conversas (atuais e futuras) sejam associadas ao mesmo contato.

Limitação: Apenas IA

Conversas via API Channel são exclusivas para agentes de IA. Não é possível transferir para atendimento humano, pois não há interface para atendimento via API.

Tipos de Mensagem

Texto

Request:

{
  "content": {
    "text": {
      "body": "Olá, como posso ajudar?"
    }
  },
  "type": "TEXT",
  "contactIdentifier": "user@example.com",
  "contactName": "Nome do Usuário"
}

Response:

{
  "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á! Como posso ajudar você hoje?"
        },
        "type": "text"
      },
      "type": "TEXT",
      "sender_type": "AI",
      "sender_name": "Aurora",
      "channel_message_id": null
    },
    {
      "content": {
        "text": {
          "body": "Estou aqui para responder suas dúvidas e ajudar com o que precisar."
        },
        "type": "text"
      },
      "type": "TEXT",
      "sender_type": "AI",
      "sender_name": "Aurora",
      "channel_message_id": null
    }
  ],
  "usage": {
    "credits": 1
  }
}

Imagem

Request:

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

Response:

{
  "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": "Vejo uma imagem interessante! Como posso ajudar com isso?"
        },
        "type": "text"
      },
      "type": "TEXT",
      "sender_type": "AI",
      "sender_name": "Aurora",
      "channel_message_id": null
    }
  ],
  "usage": {
    "credits": 1
  }
}

Áudio

Request:

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

Response:

{
  "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": "Transcrição do áudio: Olá, preciso de ajuda com meu pedido"
        },
        "type": "text"
      },
      "type": "TEXT",
      "sender_type": "AI",
      "sender_name": "Aurora",
      "channel_message_id": null
    }
  ],
  "usage": {
    "credits": 1
  }
}

Vídeo

Request:

{
  "content": {
    "video": {
      "url": "https://example.com/video.mp4",
      "caption": "Legenda do vídeo"
    }
  },
  "type": "VIDEO",
  "contactIdentifier": "user@example.com"
}

Response:

{
  "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": "Recebi seu vídeo! Como posso ajudar com isso?"
        },
        "type": "text"
      },
      "type": "TEXT",
      "sender_type": "AI",
      "sender_name": "Aurora",
      "channel_message_id": null
    }
  ],
  "usage": {
    "credits": 1
  }
}

Documento

Request:

{
  "content": {
    "document": {
      "url": "https://example.com/document.pdf",
      "filename": "documento.pdf",
      "caption": "Descrição do documento"
    }
  },
  "type": "DOCUMENT",
  "contactIdentifier": "user@example.com"
}

Response:

{
  "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": "Recebi seu documento! Como posso ajudar com isso?"
        },
        "type": "text"
      },
      "type": "TEXT",
      "sender_type": "AI",
      "sender_name": "Aurora",
      "channel_message_id": null
    }
  ],
  "usage": {
    "credits": 1
  }
}

Campos de Resposta

Campo	Tipo	Descrição
`success`	Boolean	Indica se a operação foi bem-sucedida
`contactId`	String	ID único do contato criado/encontrado
`conversationId`	String	ID único da conversa
`messageId`	String	ID único da mensagem enviada
`conversation`	Object	Informações sobre a conversa e atribuição
`aiMessages`	Array	Mensagens da IA (ordenadas em ordem crescente) - pode conter múltiplas mensagens quando a IA quebra a resposta em sequência
`usage`	Object	Informações sobre créditos consumidos

Nota sobre aiMessages

Este campo é um array porque a IA pode enviar respostas quebradas em sequência. As mensagens estão ordenadas em ordem crescente (primeira mensagem primeiro).

Códigos de Resposta

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

Exemplos de Integração

JavaScript (Fetch)
JavaScript (Axios)
Python
cURL

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();
}

// Uso
try {
  const result = await sendMessage('channel_123', 'your_api_key', 'Olá!');
  console.log('Mensagem enviada:', result);
} catch (error) {
  console.error('Erro:', error);
}

import axios from 'axios';

const api = axios.create({
  baseURL: 'https://your-domain.com',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key'
  }
});

const sendMessage = async (channelId, messageData) => {
  try {
    const response = await api.post(`/api/v1/channels/${channelId}/messages`, messageData);
    return response.data;
  } catch (error) {
    console.error('Erro ao enviar mensagem:', error.response?.data || error.message);
    throw error;
  }
};

// Exemplo de uso
const messageData = {
  content: {
    text: {
      body: 'Olá, preciso de ajuda!'
    }
  },
  type: 'TEXT',
  contactIdentifier: 'cliente@empresa.com',
  contactName: 'João Silva'
};

sendMessage('channel_123', messageData)
  .then(result => console.log('Sucesso:', result))
  .catch(error => console.error('Erro:', error));

import requests
import json

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

# Exemplo de uso
message_data = {
    "content": {
        "text": {
            "body": "Olá, preciso de ajuda!"
        }
    },
    "type": "TEXT",
    "contactIdentifier": "cliente@empresa.com",
    "contactName": "João Silva"
}

try:
    result = send_message('channel_123', 'your_api_key', message_data)
    print('Mensagem enviada:', result)
except Exception as e:
    print('Erro:', 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": "Olá, preciso de ajuda!"
      }
    },
    "type": "TEXT",
    "contactIdentifier": "cliente@empresa.com",
    "contactName": "João Silva"
  }'

Limitações

🤖 Apenas IA: Conversas são exclusivas para agentes de IA (sem atendimento humano)
📧 ContactIdentifier: Use sempre o mesmo valor para o mesmo contato (recomendamos email)
📁 Mídia: URLs devem ser acessíveis publicamente
📏 Tamanho: Limite de 10MB por arquivo
⏱️ Timeout: Downloads têm timeout de 30 segundos
🔄 Idempotência: Use X-Idempotency-Key para evitar duplicatas

Suporte

Para dúvidas ou problemas:

Endpoint​

Autenticação​

Parâmetros​

Tipos de Mensagem​

Texto​

Imagem​

Áudio​

Vídeo​

Documento​

Campos de Resposta​

Códigos de Resposta​

Exemplos de Integração​

Limitações​

Suporte​

Endpoint

Autenticação

Parâmetros

Tipos de Mensagem

Texto

Imagem

Áudio

Vídeo

Documento

Campos de Resposta

Códigos de Resposta

Exemplos de Integração

Limitações

Suporte