Telnyx Meeting Bot

Telnyx Meeting Bot

Use this skill to attend a meeting visibly, monitor its finalized transcript, alert the requester, execute explicitly authorized live rules such as speaking one response, and produce evidence-based meeting results. The bot is observe-only by default: it must not speak, send chat, or make other in-meeting changes unless the requester explicitly asks for that.

Quick Workflow

1. Resolve only missing essentials: meeting URL, join now versus a scheduled time, desired live/final outputs, and trigger/action rules. Reuse authorized details; do not ask again.
2. Persist an operation record before creating the session and choose its transport. Ordinary sessions use MCP join_meeting. Any Portal Assistant or Anam avatar session uses REST POST /v2/meeting_sessions with the requested object(s). Persist one stable idempotency_key, the transport, and the exact logical create request; store only a secret reference for a write-only Anam key. REST-only sessions are immediate, so omit join_at; Assistant sessions also omit barge_in. For an ordinary session with an authorized later speech rule, set barge_in: true so human speech can stop bot output.
3. Poll get_session, get_transcript, and, when available, get_events. Select wait_seconds from the request—about 2 for “as soon as,” reactive speech, or urgent mentions—and persist cursors, seen segments, outboxes, claims, and IDs for recovery.
4. On each new final segment, evaluate requested literal or semantic rules; deliver mention notifications through the durable outbox, and atomically claim and execute each authorized speak/send_chat action at most once.
5. On a terminal session, drain transcript pages, wait a bounded time for transcript.completed, obtain requested implemented artifact types without duplicate creation, then deliver a Markdown report.

Preconditions and Safe Defaults

• Require TELNYX_API_KEY in a backend secret store. Never include it in a URL, transcript, event, artifact, chat message, or user-facing report.
• Before joining, ensure the runtime can keep monitoring or can resume from durable background state. Do not promise end-to-end monitoring from a process that disappears without preserving and resuming the operation record.
• Verify authorization for a visible bot. A host may need to admit it; never bypass a waiting room, password, platform policy, or consent requirement.
• Default notification target: this current conversation. Do not configure a webhook_url merely to send requester notifications.
• Default behavior is immediate join, summarize_on_end: true, observe-only, and no recording-media deletion. speak, send_chat, speak_on_enter, and chat_on_enter are opt-in.
• An explicit conditional request such as “when someone asks about lunch, say ‘I want pizza’” authorizes exactly that action. Before join, persist trigger, exact payload, one-shot/repeat policy, and latency target; do not interrupt the workflow to ask again.
• Select monitoring cadence from the request: default immediate reactions and urgent mentions to wait_seconds: 2, never silently substituting a 15-second cadence for “as soon as.”
• If the link is missing, ask for it. If timing is ambiguous, ask only now versus specified time. If “my name” is not resolvable from authorized request/context/profile data, ask for name/phrases and optional variants.

Connect to the Production MCP Server

Prefer the production Streamable HTTP MCP endpoint:

https://api.telnyx.com/v2/meeting_bot/mcp
Authorization: Bearer ***

Use the service's exact tools: join_meeting, get_session, list_sessions, get_transcript, get_events, leave_meeting, get_recordings, speak, stop_speaking, send_chat, create_artifact, get_artifact, and get_artifacts.

MCP tools return one JSON text block. Decode result.content[0].text only after checking result.isError. HTTP/transport failures (for example 401, timeouts, or 5xx) differ from an HTTP-200 MCP tool failure with result.isError: true; preserve the error code/message and do not treat HTTP 200 as success alone.

If MCP is unavailable, use the equivalent production REST base:

https://api.telnyx.com/v2/meeting_sessions

REST equivalents include POST /, GET /{id}, POST /{id}/actions/speak, POST /{id}/actions/stop_speaking, POST /{id}/actions/send_chat, GET /{id}/transcript, GET /{id}/events, DELETE /{id}, GET /{id}/recordings, GET /{id}/artifacts, POST /{id}/artifacts, and GET /{id}/artifacts/{artifact_id}. Send the standard bearer-token Authorization header. REST responses use { "data": ... }. REST is a fallback transport for ordinary sessions when MCP is unavailable, but it is required for Portal Assistant and Anam avatar creates because MCP cannot express those objects. The lifecycle and durability rules remain the same.

Create or Schedule Exactly Once

Before the first session create, checkpoint a durable operation record outside transient chat memory whenever the host supports files, a task store, or durable workflow state. Store at least:

{
  "operation_id": "host-stable-id",
  "meeting_url": "redacted-or-secret-reference",
  "idempotency_key": "meeting-bot:<host-stable-id>",
  "create_transport": "mcp-or-rest",
  "create_request_without_write_only_secrets": {},
  "avatar_api_key_secret_ref": null,
  "session_id": null,
  "poll_wait_seconds": 2,
  "live_rules": [],
  "transcript_after_seq": 0,
  "event_after_seq": 0,
  "seen_transcript_seqs": [],
  "mention_alerts": [],
  "mentions": [],
  "action_claims": [],
  "artifact_requests": {},
  "known_manual_artifact_ids": [], "unreconciled_unknown_manual_creates": [],
  "transcript_completed_at": null, "summary_candidate_ids": [],
  "summary_artifact_id": null, "summary_poll_deadline_at": null,
  "summary_creation": {"state": "not_started", "attempt_count": 0, "max_pre_send_retries": 2, "artifact_id": null},
  "terminal_observed_at": null,
  "transcript_completed": false
}

Use a UUID or host-durable operation ID, not a new timestamp on retry. For an ordinary session, call MCP join_meeting with the smallest safe argument set:

{
  "meeting_url": "<resolved meeting URL>",
  "join_at": "<future RFC 3339 time only when scheduled>",
  "summarize_on_end": true,
  "idempotency_key": "meeting-bot:<host-stable-id>"
}

Omit join_at for an immediate join. Do not add greeting/chat/action arguments. If the request contains an authorized later speak rule, include "barge_in": true; this lets human speech stop bot output and does not itself make the bot speak.

For a Portal Assistant, Anam avatar, or combined session, use REST instead and persist the complete sanitized body from the sections below. Omit join_at; when an Assistant is present, omit barge_in. Persist the returned id as session_id immediately. After an uncertain create outcome, retry only through the original transport with the same logical request and idempotency_key; re-resolve an Anam key from its secret reference at dispatch instead of persisting the value. Never issue a second key, which could place a second bot in the meeting. If durable state is unavailable, disclose that duplicate prevention across restart is not guaranteed and avoid unbounded retry.

Live Session and Transcript Loop

Interleave session checks with transcript reads; a successful transcript read alone is not proof the bot attended.

1. Call get_session(id) at startup, after errors, and on a bounded cadence. Use roughly every 5–10 seconds for a reactive workflow and 15–30 seconds for passive monitoring, with backoff after transient failures.
2. Treat waiting_for_admission as a request for a meeting host to admit the visible bot. Tell the requester promptly; keep monitoring rather than claiming attendance. A non-null joined_at is the positive evidence that the bot actually attended.
3. Treat ended, failed, and admission_denied as terminal. Record status, status_detail when present, and joined_at.
4. Long-poll finalized segments with get_transcript(id, after_seq, limit, wait_seconds). Use limit: 1000 and select/persist the wait from the request: 2 seconds for “as soon as,” reactive speak, or urgent mentions; 2–5 for ordinary live updates; 10–20 for summary-only passive attendance. The implemented integer range is 0–25. The call returns as soon as new finalized speech exists, so the wait is a maximum held-request duration, not an added post-transcript delay.
5. Deduplicate by durable seq. For each new segment, persist it or its needed fields, process mentions, set after_seq to the maximum processed seq, and checkpoint before the next call.
6. If a response fills the page (1000 rows), drain immediately with the updated cursor and wait_seconds: 0 until the page is short. Then resume the short long-poll. Do not rely on a server next_after value in place of the maximum sequence you successfully processed, and never reset the cursor when a poll returns an empty page or a null continuation value. Return to the selected request cadence after the immediate drain.
7. Use get_events(id, after_seq, limit) on a bounded cadence as well; advance and persist its independent event cursor only after deduping event sequences. It is useful for lifecycle and transcript.completed evidence, but is not a replacement for transcript reads.

Use bounded retries for transient network/5xx/429 errors, for example delays of 1, 2, 4, 8, then at most 15 seconds with jitter. Keep the same session and cursors. For authentication errors, malformed requests, not_found, or an MCP result.isError that is not plausibly transient, stop automatic retries and surface the actionable error without exposing credentials or meeting secrets.

Live Trigger Detection, Alerts, and Actions

Name/phrase alerts

Match only finalized transcript segments returned by get_transcript. Normalize with Unicode case-folding and whitespace normalization. For each known name or phrase variant, use escaped whole-phrase boundaries: it must not have a letter or number immediately before or after the phrase. This lets “Ann Lee” match “ann lee,” but not “ann leeds,” and avoids false positives such as Ann inside annual. Keep variants only when known from the requester or authorized profile/context; do not invent aliases.

For every new (session_id, segment.seq, normalized_variant) match, derive one stable alert key and delivery ID such as mention:<session_id>:<segment.seq>:<normalized_variant>. Persist the mention and an outbox item before delivery:

{
  "key": "mention:<session_id>:<seq>:<normalized_variant>",
  "delivery_id": "same-stable-value",
  "status": "pending",
  "attempts": 0,
  "last_error": null,
  "sent_at": null
}

If that key already has status: "sent", skip it. If it is pending, reuse the same outbox item rather than creating a second one. Send the notice to the current conversation:

Mention detected — <speaker_label or "Unknown speaker"> at +<relative_ts>:
“<exact segment text>”

Use the segment's relative_ts (format it as a relative timestamp if available) and retain the exact quote without paraphrasing. Pass the stable delivery_id to the host notification API when it supports idempotency. Mark the outbox item sent only after confirmed delivery; otherwise leave it pending, increment its attempt metadata, and retry it with bounded backoff without blocking later transcript collection. On recovery, retry pending alerts before/alongside new segments. If the host cannot deduplicate an ambiguous send, prefer at-least-once delivery and note that a retry may duplicate the alert—never convert an unknown outcome into sent and silently lose the requested notification.

A segment can produce alerts for distinct requested terms. Append every match (term/variant, speaker, timestamp, seq, exact quote) to the durable mention log for the final report, independent of its alert-delivery status.

Explicit reactive speak or send_chat

Translate each authorized live rule into durable fields before joining:

• a stable rule_id;
• literal terms or a precise semantic condition;
• action type and exact text;
• one-shot versus explicitly requested repeat behavior;
• selected poll_wait_seconds (default 2 for immediate reactions).

For a literal rule, use the same boundary-safe matching as mention detection. For a semantic condition such as “someone asks what we should have for lunch,” evaluate each newest final segment with only a short trailing context window. Require clear transcript evidence; do not trigger from an unrelated occurrence of one keyword. Persist the evidence seq(s) and exact quote.

Before executing the first match, atomically create an action claim. A one-shot key uses only session and rule; trigger seq(s) are evidence. For an explicitly repeating literal rule, atomically claim action:<session_id>:<rule_id>:repeat:<segment.seq> once per matching finalized segment. For an explicitly repeating semantic rule, follow the repeating-action protocol; persist occurrence_first_seq and evidence_seqs. Under its ordered lease/CAS, all workers use action:<session_id>:<rule_id>:repeat:<occurrence_first_seq> and reuse the active occurrence across windows. Permit a new repeat key only after its stale-safe ordered clear commits; never key from the newest evaluation segment.

{
  "key": "action:<session_id>:<rule_id>",
  "rule_id": "lunch-question",
  "type": "speak",
  "text": "I want pizza",
  "status": "claimed",
  "trigger_seqs": [42]
}

Creating the claim only reserves its key. Dispatch only if a CAS changes claimed (or proven pre_send_failed) to dispatching immediately before the transport call; a CAS loser skips. For MCP, call speak(id, text, voice?, interrupt?); for REST, call POST /{id}/actions/speak. text is 1–4000 characters. Omit interrupt unless replacing the bot's own current audio—it does not mean “interrupt the human speaker.” The session must be active, support audio output, and have TTS configured. send_chat is similarly opt-in and may be unsupported by the meeting platform.

After MCP returns non-error { "accepted": true } or REST returns 202, mark the claim accepted; bot.speak_requested in get_events is additional durable evidence. Accepted means TTS and the provider/page handoff succeeded, not proof that every attendee heard the complete utterance. Because speak and send_chat expose no caller idempotency key, do not automatically repeat an accepted action or one whose transport outcome became ambiguous after dispatch. Mark the latter outcome_unknown, tell the requester, and keep monitoring. Within the same live attempt, only durable transport evidence that no request bytes were sent may mark pre_send_failed and allow a bounded transition of that same claim back to dispatching.

Terminal Drain and Completeness

After a terminal status, do not conclude that an empty transcript poll means the transcript is complete.

1. Record the first terminal observation time and repeatedly drain all available transcript pages as above.
2. Continue checking get_events for transcript.completed for a bounded settle window (for example up to 90 seconds, with 2–10 second backoff) while continuing short transcript drains.
3. If the completion event arrives, make one final full drain and mark transcript completeness as confirmed by transcript.completed.
4. If the bound expires without that event, make at least two empty-drain checks separated by a delay, then mark the report not confirmed; bounded settle window expired. Include the terminal status and never describe the summary as a complete account of the meeting in this case.

A failed or denied session with joined_at: null means no verified attendance; report that honestly and do not invent a discussion summary.