Meeting Sessions

Create a meeting session

Changed on

Creates a new meeting session. When an idempotency_key is supplied in the request body, replay lookup is scoped to the authenticated account and compares only the key; the request payload is not fingerprinted or compared. If a session with that key already exists for the account, the existing session is replayed (200); otherwise a new session is created (201). The session may enter asynchronous states (e.g. joining, waiting_for_admission) before becoming active. Optional camera_image input is write-only and applies only when no avatar or Assistant webpage output takes precedence. An ignored URL is not fetched. An effective URL source is resolved before bot creation; neither the source URL nor image bytes are persisted, returned, or logged. Treat signed URLs as credentials. With assistant.avatar: true, the assistant is read before the bot is created: an assistant without a Telnyx avatar configured is rejected with 400 invalid_request (message prefix assistant_avatar_not_configured:), an unknown assistant with 400 invalid_request (prefix assistant_not_found:), and a failed lookup with 503 assistant_lookup_unavailable; no bot is created in any of these cases.

post/meeting_sessions

Request

  • Base URL: https://api.telnyx.com/v2
  • URL: https://api.telnyx.com/v2/meeting_sessions
  • Auth: HTTP bearer

Request body

meeting_urlstring uri required

The meeting URL the bot should join.

bot_namestring

Display name for the bot in the meeting. Defaults to "Meeting Bot".

join_atstring date-time

ISO-8601 timestamp in the future at which the bot should join. If omitted, the bot joins immediately.

voicestring

Session-default voice identifier used for speak_on_enter and ordinary speak actions. A voice supplied on an individual speak action overrides this default for that utterance.

speak_on_enterstring

Text the bot speaks when it enters the meeting. Not spoken when an assistant is attached: the value is accepted and echoed back on the session, but the assistant owns the voice and the line is never delivered, with no event reporting the omission. Use chat_on_enter to announce an assistant-backed bot. Rejected with 400 invalid_request when assistant.avatar is true.

chat_on_enterstring

A message the bot posts to the meeting's chat as soon as it becomes active — typically a recording disclosure. Delivered at most once. Independent of speak_on_enter: both may be set, and the chat message posts first because it does not wait for text-to-speech or avatar startup. Rejected with 422 unsupported_capability on platforms without meeting chat.

barge_inboolean

When enabled, a human participant speech_on event interrupts and stops the current bot audio; it does not bypass admission or initiate speech. Assistant sessions reject barge_in: true.

summarize_on_endboolean

If true, generate a summary artifact when the session ends.

webhook_urlstring uri

HTTPS endpoint to receive session lifecycle callbacks. Static validation requires HTTPS, rejects embedded credentials and blocked hosts, and enforces egress policy. Validation makes no network request to the endpoint.

metadataobject

Arbitrary key-value metadata attached to the session. The serialized JSON representation must not exceed 16384 characters at runtime.

idempotency_keystring

Client-supplied idempotency key to safely retry creation requests without duplicating sessions. Lookup is scoped to the authenticated account and compares the key only; the request payload is not fingerprinted or compared.

Example request

{
  "meeting_url": "https://zoom.us/j/1234567890",
  "bot_name": "Notetaker"
}

Response

Replayed existing meeting session matching the account-scoped idempotency_key. Replay is key-only; the request payload is not fingerprinted or compared.

Changes

  • da303e40b51eRevision changes
    • breaking

      the response property const value changed from anam to telnyx for the status

    • breaking

      the response property const value changed from anam to telnyx for the status

    • warning

      removed the request property

    • info

      added the new optional request property /

    • info

      added the required property /// to the response with the status

    • info

      added the required property /// to the response with the status

    • info

      added the required property /// to the response with the status

    • info

      added the required property /// to the response with the status

  • cdb64ddf086fRevision changes
    • breaking

      removed the enum value none of the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      added the new full_duplex enum value to the /// response property for the response status

    • warning

      added the new full_duplex enum value to the /// response property for the response status

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property

    • info

      the request property default value changed from none to half_duplex

    • info

      added the new full_duplex enum value to the request property /

    • info

      removed the none enum value from the /// response property for the response status

    • info

      removed the none enum value from the /// response property for the response status

    • info

      added the required property /// to the response with the status

    • info

      added the required property /// to the response with the status

    • info

      added the required property /// to the response with the status

    • info

      added the required property /// to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status