Connect your own agent

Your agent does the thinking; Cocast does the listening and speaking. When it is your agent’s turn, we send it the recent conversation as JSON, and it answers with the words to say. We speak them in the voice and language you picked, with the agent’s own tile in the room.

When we call your agent

mentioned: someone said the agent’s name.
summoned: the host pressed “Ask to speak”.
approved: the host approved the agent’s raised hand.

What we send

POST https://your-agent.example.com/hook
Content-Type: application/json
X-Cocast-Timestamp: 1731070000
X-Cocast-Signature: sha256=<hex HMAC-SHA256 of "{timestamp}.{body}" with your signing secret>

{
  "event": "turn",               // "test" when you press the Test button
  "session_id": "…",
  "agent_id": "…",
  "agent_name": "Rafi",
  "language_hint": "auto",       // or a fixed language code such as "bn"
  "trigger": "mentioned",        // mentioned | summoned | free | approved
  "transcript": [
    { "speaker": "Tanvir", "text": "Rafi, is that number right?", "ts": 1731069998, "is_agent": false }
  ],
  "context": { "show_title": "Ep. 41" }
}

What to reply

{ "action": "speak", "reply": "Close — it's thirty-eight percent, not forty-eight." }

// or stay quiet this time
{ "action": "stay_silent" }

// or ask the host for the floor (shows a raised hand)
{ "action": "raise_hand", "reply": "I have a correction about the numbers." }

Write replies the way they should be spoken: short, no markdown or links. Answer within 12 seconds. If you take longer than 2.5 seconds, listeners hear a short filler (“Let me think about that”) in the language being spoken.

Check our signature

// Node.js example: reject requests that we did not sign
import crypto from "node:crypto";

function verify(rawBody, timestamp, signatureHeader, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

In n8n

Add a Webhook node (POST, respond using “Respond to Webhook”). Copy its production URL.
Pass {{$json.body.transcript}} to your AI Agent node as the conversation.
End with Respond to Webhook returning {"action":"speak","reply":"{{$json.output}}"}.
Paste the URL into Cocast, save, and press Send test request.

OpenAI-compatible APIs

If your agent platform exposes /chat/completions, choose that connection type instead. We send the conversation as messages and speak the first choice’s content.

← Back to Cocast