> ## Documentation Index > Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a meeting session > 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). Supports bring-your-own-key (BYOK) configuration. 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. ## OpenAPI ````yaml /openapi/source/external/meeting-sessions/meeting-sessions.json post /meeting_sessions openapi: 3.1.0 info: title: Telnyx Meeting Sessions API version: 2.0.0 description: >- Programmatically create, control, and inspect Telnyx Meeting Sessions, including real-time actions, events, transcripts, recordings, and artifacts. x-latency-category: interactive x-endpoint-cost: light servers: - url: https://api.telnyx.com/v2 security: - bearerAuth: [] tags: - name: Meeting Sessions description: Create, list, retrieve, update, and stop meeting sessions. - name: Meeting Session Actions description: Send real-time speech and chat actions to an active meeting session. - name: Meeting Session Data description: >- Read lifecycle events, transcript segments, and recordings for a meeting session. - name: Meeting Session Artifacts description: Create and retrieve asynchronous summaries and action-item artifacts. - name: Meeting Session Webhooks description: Outbound webhook deliveries for meeting session events. paths: /meeting_sessions: post: tags: - Meeting Sessions summary: Create a meeting session description: >- 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). Supports bring-your-own-key (BYOK) configuration. 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. operationId: createMeetingSession requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateMeetingSessionRequest' responses: '200': description: >- Replayed existing meeting session matching the account-scoped idempotency_key. Replay is key-only; the request payload is not fingerprinted or compared. content: application/json: schema: $ref: '#/components/schemas/MeetingSessionResponse' '201': description: New meeting session created. content: application/json: schema: $ref: '#/components/schemas/CreateMeetingSessionResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '413': $ref: '#/components/responses/PayloadTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/MeetingCreateProviderError' '503': $ref: '#/components/responses/ServiceUnavailable' components: schemas: CreateMeetingSessionRequest: title: CreateMeetingSessionRequest type: object additionalProperties: false description: >- Request body for creating a new meeting session. Cross-field rules: - Neither `avatar` nor `assistant` can be combined with `join_at`; both are available only for sessions that join immediately. - `assistant` cannot be combined with `barge_in: true`. - The `avatar` and `assistant` options take effect at session creation and cannot be modified later. - An effective Avatar or Assistant webpage output takes precedence over `camera_image`; the static image is ignored and a URL source is not fetched. required: - meeting_url properties: meeting_url: type: string format: uri description: The meeting URL the bot should join. bot_name: type: string minLength: 1 maxLength: 100 description: Display name for the bot in the meeting. Defaults to "Meeting Bot". join_at: type: string format: date-time description: >- ISO-8601 timestamp in the future at which the bot should join. If omitted, the bot joins immediately. voice: type: string minLength: 1 maxLength: 100 description: >- 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_enter: type: string minLength: 1 maxLength: 4000 description: Text the bot speaks when it enters the meeting. barge_in: type: boolean default: false description: >- 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_end: type: boolean default: false description: If true, generate a summary artifact when the session ends. camera_image: $ref: '#/components/schemas/MeetingSessionCameraImage' webhook_url: type: string format: uri description: >- 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. metadata: type: object additionalProperties: true description: >- Arbitrary key-value metadata attached to the session. The serialized JSON representation must not exceed 16384 characters at runtime. idempotency_key: type: string minLength: 1 maxLength: 255 description: >- 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. avatar: $ref: '#/components/schemas/MeetingSessionAvatarRequest' assistant: $ref: '#/components/schemas/MeetingSessionAssistantRequest' examples: - meeting_url: https://zoom.us/j/1234567890 bot_name: Notetaker - meeting_url: https://meet.google.com/abc-defg-hij bot_name: Avatar Bot avatar: provider: anam avatar_id: avatar_fake-001 api_key: fake_avatar_api_key_do_not_use - meeting_url: https://teams.microsoft.com/l/meetup-join/example bot_name: Voice Assistant assistant: id: asst_fake-uuid-1234 call_control_connection_id: conn-fake-abcdef from: '+12025550199' loopback_sip_uri: sip:loopback@example.invalid audio_gate: half_duplex MeetingSessionResponse: type: object additionalProperties: false required: - data properties: data: $ref: '#/components/schemas/MeetingSession' CreateMeetingSessionResponse: type: object additionalProperties: false required: - data properties: data: $ref: '#/components/schemas/MeetingSessionCreated' MeetingSessionCameraImage: title: MeetingSessionCameraImage type: object description: >- Write-only static camera-tile image for this session, not a native account or participant profile photo. Supply exactly one JPEG source. When effective, the image is used as the bot's static camera/video output; presentation varies by meeting platform and recording configuration and is not guaranteed in recordings. An effective Avatar or Assistant webpage output takes precedence, so this input is ignored and a URL source is not fetched. writeOnly: true oneOf: - $ref: '#/components/schemas/MeetingSessionCameraImageBase64Source' - $ref: '#/components/schemas/MeetingSessionCameraImageUrlSource' MeetingSessionAvatarRequest: title: MeetingSessionAvatarRequest type: object additionalProperties: false description: >- Request options for attaching a bring-your-own-key avatar to the session. required: - provider - avatar_id - api_key properties: provider: type: string const: anam description: Avatar provider identifier. Currently only "anam" is supported. avatar_id: type: string minLength: 1 maxLength: 100 description: Identifier of the avatar to use. api_key: type: string minLength: 1 maxLength: 4096 writeOnly: true description: >- Bring-your-own-key API key for the avatar provider. The key is never stored or returned by the API. MeetingSessionAssistantRequest: title: MeetingSessionAssistantRequest type: object additionalProperties: false description: >- Request options for attaching a voice assistant to the session. Routing fields (`call_control_connection_id`, `from`, and `loopback_sip_uri`) are used only to establish the assistant call leg and are omitted from response objects. `audio_gate` is returned with `id` in the assistant response object. required: - id - call_control_connection_id - from - loopback_sip_uri properties: id: type: string minLength: 1 maxLength: 255 description: Identifier of the assistant to attach. call_control_connection_id: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,254}$ description: >- Call control connection used to bridge the assistant into the meeting audio. from: type: string pattern: ^\+[1-9]\d{6,14}$ description: >- E.164 calling number used as the originating party for the assistant call leg. examples: - '+12025550199' loopback_sip_uri: type: string minLength: 1 maxLength: 2048 pattern: ^sip:[^\s]+$ description: SIP URI to which the assistant media loopback is established. audio_gate: type: string enum: - none - half_duplex default: none description: Audio gating strategy for the assistant call leg. MeetingSession: title: MeetingSession type: object additionalProperties: false description: >- Represents a meeting session. All serializer fields are present and required; nullable fields use null when absent. No actor, provider-bot, idempotency, routing, key, or internal fields are exposed. required: - id - account_id - provider - status - status_detail - recording - meeting_url - platform - bot_name - config - avatar - avatar_state - avatar_state_changed_at - assistant - assistant_state - assistant_state_changed_at - webhook_url - metadata - failure_reason - created_at - join_at - joined_at - ended_at - updated_at properties: id: type: string description: Unique identifier for the meeting session. account_id: type: string description: Identifier of the owning account. provider: type: string description: Provider handling the meeting session. status: type: string enum: - scheduled - joining - waiting_for_admission - active - leaving - ended - failed - admission_denied description: >- Lifecycle status. `waiting_for_admission` means the bot reached the meeting lobby and may require host approval. `active` means the bot entered the meeting/media path. `ended` alone does not prove attendance; use non-null `joined_at` as positive evidence that the session became active. `admission_denied` is reserved for an explicit provider denial, while cancellation or another termination can end a never-admitted session as `ended`. status_detail: type: - string - 'null' description: Additional human-readable detail about the status, or null. recording: type: boolean description: Whether the session is being recorded. meeting_url: type: string format: uri description: The meeting URL the bot joins. platform: type: string enum: - zoom - google_meet - teams - webex - unknown description: Detected meeting platform. bot_name: type: string description: Display name of the bot in the meeting. config: $ref: '#/components/schemas/MeetingSessionConfig' avatar: oneOf: - $ref: '#/components/schemas/MeetingSessionAvatar' - type: 'null' description: Avatar configuration if an avatar is attached, otherwise null. avatar_state: type: - string - 'null' enum: - starting - connected - degraded - disconnected - null description: >- Current state of the avatar connection, or null if no avatar is attached. avatar_state_changed_at: type: - string - 'null' format: date-time description: Timestamp of the last avatar state change, or null. assistant: oneOf: - $ref: '#/components/schemas/MeetingSessionAssistant' - type: 'null' description: Assistant configuration if an assistant is attached, otherwise null. assistant_state: type: - string - 'null' enum: - starting - connected - failed - ended - null description: Current state of the assistant, or null if no assistant is attached. assistant_state_changed_at: type: - string - 'null' format: date-time description: Timestamp of the last assistant state change, or null. webhook_url: type: - string - 'null' format: uri description: >- Webhook endpoint for session lifecycle callbacks, or null if not configured. metadata: type: object additionalProperties: true description: Arbitrary key-value metadata attached to the session. failure_reason: type: - string - 'null' description: Human-readable failure reason if the session failed, or null. created_at: type: string format: date-time description: Timestamp when the session was created. join_at: type: - string - 'null' format: date-time description: Scheduled join time, or null for immediate join. joined_at: type: - string - 'null' format: date-time description: >- Timestamp when the session first became `active`, or null if it never became active. This remains positive admission evidence after terminal transitions. ended_at: type: - string - 'null' format: date-time description: Timestamp when the session ended, or null if ongoing. updated_at: type: string format: date-time description: Timestamp of the last update to the session. MeetingSessionCreated: title: MeetingSessionCreated type: object additionalProperties: false description: >- Response returned when a meeting session is first created. It is a full session representation plus an optional `webhook_secret` that is returned only on the first successful create when a `webhook_url` is configured. The secret is never replayed, listed, or retrievable on subsequent requests. No actor, provider-bot, idempotency, routing, key, or internal fields are exposed. required: - id - account_id - provider - status - status_detail - recording - meeting_url - platform - bot_name - config - avatar - avatar_state - avatar_state_changed_at - assistant - assistant_state - assistant_state_changed_at - webhook_url - metadata - failure_reason - created_at - join_at - joined_at - ended_at - updated_at properties: id: type: string description: Unique identifier for the meeting session. account_id: type: string description: Identifier of the owning account. provider: type: string description: Provider handling the meeting session. status: type: string enum: - scheduled - joining - waiting_for_admission - active - leaving - ended - failed - admission_denied description: >- Lifecycle status. `waiting_for_admission` means the bot reached the meeting lobby and may require host approval. `active` means the bot entered the meeting/media path. `ended` alone does not prove attendance; use non-null `joined_at` as positive evidence that the session became active. `admission_denied` is reserved for an explicit provider denial, while cancellation or another termination can end a never-admitted session as `ended`. status_detail: type: - string - 'null' description: Additional human-readable detail about the status, or null. recording: type: boolean description: Whether the session is being recorded. meeting_url: type: string format: uri description: The meeting URL the bot joins. platform: type: string enum: - zoom - google_meet - teams - webex - unknown description: Detected meeting platform. bot_name: type: string description: Display name of the bot in the meeting. config: $ref: '#/components/schemas/MeetingSessionConfig' avatar: oneOf: - $ref: '#/components/schemas/MeetingSessionAvatar' - type: 'null' description: Avatar configuration if an avatar is attached, otherwise null. avatar_state: type: - string - 'null' enum: - starting - connected - degraded - disconnected - null description: >- Current state of the avatar connection, or null if no avatar is attached. avatar_state_changed_at: type: - string - 'null' format: date-time description: Timestamp of the last avatar state change, or null. assistant: oneOf: - $ref: '#/components/schemas/MeetingSessionAssistant' - type: 'null' description: Assistant configuration if an assistant is attached, otherwise null. assistant_state: type: - string - 'null' enum: - starting - connected - failed - ended - null description: Current state of the assistant, or null if no assistant is attached. assistant_state_changed_at: type: - string - 'null' format: date-time description: Timestamp of the last assistant state change, or null. webhook_url: type: - string - 'null' format: uri description: >- Webhook endpoint for session lifecycle callbacks, or null if not configured. metadata: type: object additionalProperties: true description: Arbitrary key-value metadata attached to the session. failure_reason: type: - string - 'null' description: Human-readable failure reason if the session failed, or null. created_at: type: string format: date-time description: Timestamp when the session was created. join_at: type: - string - 'null' format: date-time description: Scheduled join time, or null for immediate join. joined_at: type: - string - 'null' format: date-time description: >- Timestamp when the session first became `active`, or null if it never became active. This remains positive admission evidence after terminal transitions. ended_at: type: - string - 'null' format: date-time description: Timestamp when the session ended, or null if ongoing. updated_at: type: string format: date-time description: Timestamp of the last update to the session. webhook_secret: type: string readOnly: true description: >- Secret for validating webhook signatures. Returned only on the first successful create when `webhook_url` is configured. Never replayed, listed, or retrievable on subsequent requests. examples: - id: mtgsess_a1b2c3d4-e5f6-7890-abcd-ef1234567890 account_id: acct_fake-uuid-0001 provider: recall status: scheduled status_detail: null recording: false meeting_url: https://zoom.us/j/1234567890 platform: zoom bot_name: Notetaker config: voice: null speak_on_enter: null barge_in: false summarize_on_end: false avatar: null avatar_state: null avatar_state_changed_at: null assistant: null assistant_state: null assistant_state_changed_at: null webhook_url: null metadata: {} failure_reason: null created_at: '2026-07-30T12:00:00Z' join_at: '2026-07-30T13:00:00Z' joined_at: null ended_at: null updated_at: '2026-07-30T12:00:00Z' - id: mtgsess_b2c3d4e5-f6a7-8901-bcde-f23456789012 account_id: acct_fake-uuid-0002 provider: recall status: joining status_detail: null recording: false meeting_url: https://teams.microsoft.com/l/meetup-join/example platform: teams bot_name: Voice Assistant config: voice: voice-fake-001 speak_on_enter: Hello, I am joining. barge_in: false summarize_on_end: true avatar: null avatar_state: null avatar_state_changed_at: null assistant: id: asst_fake-uuid-1234 audio_gate: half_duplex assistant_state: starting assistant_state_changed_at: '2026-07-30T12:00:00Z' webhook_url: https://example.invalid/webhooks/sessions metadata: {} failure_reason: null created_at: '2026-07-30T12:00:00Z' join_at: null joined_at: null ended_at: null updated_at: '2026-07-30T12:00:00Z' webhook_secret: whsec_example_do_not_use ErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - code - message properties: code: type: string message: type: string examples: - error: code: invalid_request message: webhook_url is disabled - error: code: not_found message: meeting session not found - error: code: unsupported_capability message: avatar video is not supported on platform 'unknown' - error: code: internal_error message: internal server error MeetingSessionCameraImageBase64Source: title: MeetingSessionCameraImageBase64Source type: object additionalProperties: false required: - format - base64_data properties: format: type: string const: jpeg description: Only JPEG images are accepted. base64_data: type: string minLength: 4 maxLength: 1835008 pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ description: >- Canonical plain RFC 4648 Base64 for a valid decoded JPEG. Data URIs, whitespace, and the URL-safe alphabet are rejected. The encoded value is limited to 1,835,008 characters and the decoded JPEG to 1,363,148 bytes. The JPEG is limited to 4,096 pixels per dimension, 4 megapixels, and 128 MB of decoder memory. The image bytes are not persisted, returned, or logged. examples: - format: jpeg base64_data: >- /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgMCAgMDAwMEAwMEBQgFBQQEBQoHBwYIDAoMDAsKCwsNDhIQDQ4RDgsLEBYQERMUFRUVDA8XGBYUGBIUFRT/wAALCAACAAIBAREA/8QAFAABAAAAAAAAAAAAAAAAAAAACP/EAB4QAAAEBwAAAAAAAAAAAAAAAAAEBgcCFic1RVNi/9oACAEBAAA/AH8hGJbWR09TxKW4vhC2qHgf/9k= MeetingSessionCameraImageUrlSource: title: MeetingSessionCameraImageUrlSource type: object additionalProperties: false required: - format - url properties: format: type: string const: jpeg description: Only JPEG images are accepted. url: type: string format: uri minLength: 1 maxLength: 2048 pattern: ^[Hh][Tt][Tt][Pp][Ss]:// description: >- Public HTTPS JPEG URL with at most 2,048 characters and no credentials, fragment, surrounding whitespace, raw control characters, or explicit non-default port. Signed queries are allowed but must be treated as credentials. Fetching is limited to public network destinations, a five-second timeout, no redirects, a 2xx image/jpeg response with identity or no content encoding, and a 1,363,148-byte limit enforced against both declared and streamed content. The service resolves the URL before bot creation and does not persist, return, or log the URL or image bytes. examples: - format: jpeg url: https://cdn.example.com/bot-camera.jpg MeetingSessionConfig: title: MeetingSessionConfig type: object additionalProperties: false required: - voice - speak_on_enter - barge_in - summarize_on_end properties: voice: type: - string - 'null' description: Configured voice identifier, or null if not set. speak_on_enter: type: - string - 'null' description: Text spoken on meeting entry, or null if not set. barge_in: type: boolean description: >- 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_end: type: boolean description: Whether a summary artifact is generated on session end. MeetingSessionAvatar: title: MeetingSessionAvatar type: object additionalProperties: false required: - provider - avatar_id properties: provider: type: string const: anam description: Avatar provider identifier. avatar_id: type: string description: Identifier of the avatar. MeetingSessionAssistant: title: MeetingSessionAssistant type: object additionalProperties: false required: - id - audio_gate properties: id: type: string description: Identifier of the assistant. audio_gate: type: string enum: - none - half_duplex description: Audio gating strategy for the assistant call leg. responses: BadRequest: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: invalid_request message: request is invalid Unauthorized: description: >- Unauthorized. On api.telnyx.com, authentication is enforced by the API gateway before the request reaches the Meeting service, so a missing or invalid API key returns the standard Telnyx error envelope (`{"errors": [{"code": "10009", ...}]}`) rather than the single-`error` shape below. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthorized message: invalid or missing credentials Forbidden: description: The authenticated credential is not permitted to perform this operation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: forbidden message: credential is not permitted PayloadTooLarge: description: Payload Too Large content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: invalid_request message: request body too large UnprocessableEntity: description: Unprocessable Entity, including an unsupported capability content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unsupported_capability message: avatar video is not supported on platform 'unknown' TooManyRequests: description: >- Authentication is temporarily overloaded. Retry after the number of seconds in `Retry-After`. headers: Retry-After: required: true description: Seconds to wait before retrying. schema: type: integer minimum: 1 maximum: 5 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: auth_overloaded message: authentication temporarily overloaded InternalServerError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: internal_error message: internal server error MeetingCreateProviderError: description: The meeting provider rejected bot creation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: provider_error message: meeting provider rejected bot creation ServiceUnavailable: description: >- A required feature or dependency is not configured or authentication is unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: not_configured message: required feature is not configured securitySchemes: bearerAuth: type: http scheme: bearer ````