Our most capable AI model is now on the Scale plan. See plans

Docs/Custom channelsAPI reference

Custom channels

Any platform can talk to your agent: relay what customers write to the API, and relay the agent's replies back. Conversations show in the inbox with a Custom badge, count towards your usage and plan limits, and can be handed to your team like any other.

What you need

  1. An API key (Settings → API keys) with Send messages turned on (the messages:write scope), limited to the agent.
  2. A webhook endpoint (Agent → Developers → Webhooks) subscribed to message.sent, if you want team replies and handoff notices, or use async mode.

Sending a customer message

curl https://www.igentrix.com/api/v1/agents/YOUR_AGENT_ID/messages \
  -H "Authorization: Bearer $IGENTRIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "chat-42",
    "sender": { "id": "user-7", "name": "Thandi" },
    "text": "Do you deliver to my area?"
  }'

Messages with the same conversationId continue one conversation. In the default sync mode the response has the reply:

{ "data": { "conversationId": "Xy12…", "status": "answered", "reply": "Yes, within 2–3 working days.", "notices": [], "handoff": { "status": "active" } } }

Send it, then each of notices, to the customer. With "mode": "async" the API answers 202 straight away and the reply arrives as a message.sent webhook event instead.

You can also pass contact (email, phone) and up to three mediaUrls (public https images, audio, video or PDFs).

Handoff

When the conversation is with your team, status is held and there's no reply: your team member's replies, and notices like "You're now chatting with Thabo", arrive as message.sent events with role human_agent or system. Relay every message.sent event whose conversation source is custom, and your channel supports handoff automatically.

Example: a Telegram relay in ~50 lines

// relay.mjs (Node 20+). Env: TELEGRAM_TOKEN, IGENTRIX_KEY, IGENTRIX_AGENT, IGENTRIX_WEBHOOK_SECRET
import http from "node:http";
import crypto from "node:crypto";

const { TELEGRAM_TOKEN, IGENTRIX_KEY, IGENTRIX_AGENT, IGENTRIX_WEBHOOK_SECRET } = process.env;
const TG = `https://api.telegram.org/bot${TELEGRAM_TOKEN}`;
const API = `https://www.igentrix.com/api/v1/agents/${IGENTRIX_AGENT}/messages`;

const sendTelegram = (chatId, text) =>
  fetch(`${TG}/sendMessage`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ chat_id: chatId, text })
  });

// 1. Forward customer messages to the agent. Replies come back as webhooks.
let offset = 0;
async function poll() {
  const updates = await fetch(`${TG}/getUpdates?timeout=30&offset=${offset}`).then((r) => r.json());
  for (const u of updates.result ?? []) {
    offset = u.update_id + 1;
    const m = u.message;
    if (!m?.text) continue;
    await fetch(API, {
      method: "POST",
      headers: { Authorization: `Bearer ${IGENTRIX_KEY}`, "Content-Type": "application/json" },
      body: JSON.stringify({
        conversationId: String(m.chat.id),
        sender: { id: String(m.from.id), name: m.from.first_name },
        text: m.text,
        mode: "async"
      })
    });
  }
  setImmediate(poll);
}

// 2. Relay the agent's replies, team replies and notices back to Telegram.
http
  .createServer(async (req, res) => {
    let body = "";
    for await (const chunk of req) body += chunk;
    const ts = req.headers["x-igentrix-timestamp"];
    const expected = "sha256=" + crypto.createHmac("sha256", IGENTRIX_WEBHOOK_SECRET).update(`${ts}.${body}`).digest("hex");
    if (req.headers["x-igentrix-signature"] !== expected) return res.writeHead(401).end();
    const event = JSON.parse(body);
    const conv = event.data?.conversation;
    if (event.type === "message.sent" && conv?.source === "custom") {
      await sendTelegram(conv.externalId.replace(/^custom:/, ""), event.data.message.text);
    }
    res.writeHead(200).end();
  })
  .listen(3000);

poll();

Point a webhook endpoint at the relay's public URL (port 3000), subscribed to message.sent, and use its signing secret as IGENTRIX_WEBHOOK_SECRET. In production, also reject timestamps older than five minutes and deduplicate on the event id.