TeXML REST Commands

Dial a new conference participant

Changed on

Dials a new participant into the specified conference and returns the created participant resource.

post/texml/Accounts/{account_sid}/Conferences/{conference_sid}/Participants

Request

  • Base URL: https://api.telnyx.com/v2
  • URL: https://api.telnyx.com/v2/texml/Accounts/{account_sid}/Conferences/{conference_sid}/Participants
  • Auth: HTTP bearer

Path parameters

account_sidstring required
Example:f5586561-8ff0-4291-a51b-c7dfe4139ff9

The UUID of the Telnyx account that owns the resource, for example f5586561-8ff0-4291-a51b-c7dfe4139ff9. The account_sid path segment is kept for Twilio API compatibility, but the value is a Telnyx account UUID, not a Twilio AC... SID. It must match the account that owns the API key used to authenticate the request, otherwise the endpoint returns 404. The same value is sent as AccountSid in TeXML webhooks.

conference_sidstring required

The ConferenceSid that uniquely identifies a conference.

Request body application/x-www-form-urlencoded

Beep'true' | 'false' | 'onEnter' | 'onExit'

Whether to play a notification beep to the conference when the participant enters and exits.

StatusCallbackstring

URL destination for Telnyx to send status callback events to for the call.

StatusCallbackMethod'GET' | 'POST'

HTTP request type used for StatusCallback.

StatusCallbackEventstring

The changes to the call's state that should generate a call to StatusCallback. Can be: initiated, ringing, answered, and completed. Separate multiple values with a space. The default value is completed.

Tostring

The phone number of the called party. Phone numbers are formatted with a + and country code.

Fromstring

The phone number of the party that initiated the call. Phone numbers are formatted with a + and country code.

Timeoutinteger

The number of seconds that we should allow the phone to ring before assuming there is no answer. Can be an integer between 5 and 120, inclusive. The default value is 30.

Mutedboolean

Whether the participant should be muted.

StartConferenceOnEnterboolean

Whether to start the conference when the participant enters. Defaults to true.

EndConferenceOnExitboolean

Whether to end the conference when the participant leaves. Defaults to false.

Labelstring

A unique label for the participant that will be added to the conference. The label can be used to reference the participant for updates via the TeXML REST API.

EarlyMediaboolean

Whether participant shall be bridged to conference before the participant answers (from early media if available). Defaults to false.

ConferenceStatusCallbackstring

The URL the conference callbacks will be sent to.

ConferenceStatusCallbackMethod'GET' | 'POST'

HTTP request type used for ConferenceStatusCallback. Defaults to POST.

ConferenceStatusCallbackEventstring

The changes to the conference's state that should generate a call to ConferenceStatusCallback. Can be: start, end, join and leave. Separate multiple values with a space. By default no callbacks are sent.

WaitUrlstring

The URL to call for an audio file to play while the participant is waiting for the conference to start.

MaxParticipantsinteger

The maximum number of participants in the conference. Can be a positive integer from 2 to 800. The default value is 250.

Coachingboolean

Whether the participant is coaching another call. When true, CallSidToCoach has to be given.

CallSidToCoachstring

The SID of the participant who is being coached. The participant being coached is the only participant who can hear the participant who is coaching.

CallerIdstring

To be used as the caller id name (SIP From Display Name) presented to the destination (To number). The string should have a maximum of 128 characters, containing only letters, numbers, spaces, and -_~!.+ special characters. If ommited, the display name will be the same as the number in the From field.

TimeLimitinteger

The maximum duration of the call in seconds.

MachineDetection'Enable' | 'DetectMessageEnd'

Whether to detect if a human or an answering machine picked up the call. Use Enable if you would like to ne notified as soon as the called party is identified. Use DetectMessageEnd, if you would like to leave a message on an answering machine.

MachineDetectionTimeoutinteger

How long answering machine detection should go on for before sending an Unknown result. Given in milliseconds.

MachineDetectionSpeechThresholdinteger

Maximum threshold of a human greeting. If greeting longer than this value, considered machine. Ignored when premium detection is used.

MachineDetectionSpeechEndThresholdinteger

Silence duration threshold after a greeting message or voice for it be considered human. Ignored when premium detection is used.

MachineDetectionSilenceTimeoutinteger

If initial silence duration is greater than this value, consider it a machine. Ignored when premium detection is used.

MachineDetectionBeepProfile'both' | 'freq_only'

Selects which detectors must validate a beep. both requires the amplitude and frequency detectors to agree. freq_only uses the frequency detector alone, for beeps whose volume is too unsteady for the default profile. Only used when MachineDetection is enabled.

MachineDetectionBeepMinFrequencyinteger

Lowest frequency, in Hz, that a tone must reach to be treated as a beep. Raising it above 480 excludes North American ringback (440 + 480 Hz), which can otherwise be reported as a beep when the freq_only profile is in use. Only used when MachineDetection is enabled.

MachineDetectionBeepMaxFrequencyinteger

Highest frequency, in Hz, that a tone can reach and still be treated as a beep. Only used when MachineDetection is enabled.

MachineDetectionBeepMinToneDurationinteger

Shortest tone, in milliseconds, that can be treated as a beep. Raising it rejects brief tones such as call-progress blips. Only used when MachineDetection is enabled.

MachineDetectionBeepSpectralConfirmationboolean

When enabled, a candidate beep must pass an additional spectral check before it is reported. Only used when MachineDetection is enabled.

MachineDetectionBeepSpectralWindowinteger

Length of the spectral confirmation window, in milliseconds. Only used when MachineDetection is enabled.

MachineDetectionBeepSpectralMinPuritynumber

Minimum spectral purity, from 0 to 1, for a tone to be treated as a beep. Raising it rejects mixed tones such as ringback, which combines two frequencies. Only used when MachineDetection is enabled.

MachineDetectionBeepSpectralRejectFaxCngboolean

When enabled, the fax CNG tone is rejected rather than reported as a beep. Only used when MachineDetection is enabled.

AmdStatusCallbackstring

The URL the result of answering machine detection will be sent to.

AmdStatusCallbackMethod'GET' | 'POST'

HTTP request type used for AmdStatusCallback. Defaults to POST.

ApplicationSidstring

The SID of the TeXML application that will handle the new participant's call. Required unless joining an existing conference by its ConferenceSid.

CancelPlaybackOnMachineDetectionboolean

Whether to cancel ongoing playback on machine detection. Defaults to true.

CancelPlaybackOnDetectMessageEndboolean

Whether to cancel ongoing playback on greeting ended detection. Defaults to true.

PreferredCodecsstring

The list of comma-separated codecs to be offered on a call.

Recordboolean

Whether to record the entire participant's call leg. Defaults to false.

RecordingChannels'mono' | 'dual'

The number of channels in the final recording. Defaults to mono.

RecordingStatusCallbackstring

The URL the recording callbacks will be sent to.

RecordingStatusCallbackMethod'GET' | 'POST'

HTTP request type used for RecordingStatusCallback. Defaults to POST.

RecordingStatusCallbackEventstring

The changes to the recording's state that should generate a call to RecoridngStatusCallback. Can be: in-progress, completed and absent. Separate multiple values with a space. Defaults to completed.

RecordingTrack'inbound' | 'outbound' | 'both'

The audio track to record for the call. The default is both.

SipAuthPasswordstring

The password to use for SIP authentication.

SipAuthUsernamestring

The username to use for SIP authentication.

Trim'trim-silence' | 'do-not-trim'

Whether to trim any leading and trailing silence from the recording. Defaults to trim-silence.

ConferenceRecord'true' | 'false' | 'record-from-start' | 'do-not-record'

Whether to record the conference the participant is joining. Defualts to do-not-record. The boolean values true and false are synonymous with record-from-start and do-not-record respectively.

ConferenceRecordingStatusCallbackstring

The URL the conference recording callbacks will be sent to.

ConferenceRecordingStatusCallbackMethod'GET' | 'POST'

HTTP request type used for ConferenceRecordingStatusCallback. Defaults to POST.

ConferenceRecordingStatusCallbackEventstring

The changes to the conference recording's state that should generate a call to RecoridngStatusCallback. Can be: in-progress, completed and absent. Separate multiple values with a space. Defaults to completed. failed and absent are synonymous.

ConferenceRecordingTimeoutinteger

The number of seconds that Telnyx will wait for the recording to be stopped if silence is detected. The timer only starts when the speech is detected. Please note that the transcription is used to detect silence and the related charge will be applied. The minimum value is 0. The default value is 0 (infinite)

ConferenceTrim'trim-silence' | 'do-not-trim'

Whether to trim any leading and trailing silence from the conference recording. Defaults to trim-silence.

Example request

{
  "To": "+12065550100",
  "From": "+12065550200"
}

Response

New participant resource.

account_sidstring

The id of the account the resource belongs to.

call_sidstring

The identifier of this participant's call.

coachingboolean

Whether the participant is coaching another call.

coaching_call_sidstring

The identifier of the coached participant's call.

end_conference_on_exitboolean

Whether the conference ends when the participant leaves.

holdboolean

Whether the participant is on hold.

mutedboolean

Whether the participant is muted.

status'connecting' | 'connected' | 'completed'

The status of the participant's call in the conference.

uristring

The relative URI for this participant.

conference_sidstring uuid

The unique identifier for the conference.

Example response

{
  "account_sid": "4e71926f-8f13-450e-b91c-23c2ef786aa6",
  "call_sid": "v3:9X2vxPDFY2RHSJ1EdMS0RHRksMTg7ldNxdjWbVr9zBjbGjGsSe-aiQ",
  "coaching": false,
  "conference_sid": "cd5a70f4-759b-4d5e-9c06-88c00f16f3c1",
  "end_conference_on_exit": false,
  "hold": false,
  "muted": false,
  "status": "completed",
  "uri": "/v2/texml/Accounts/4e71926f-8f13-450e-b91c-23c2ef786aa6/Conferences/cd5a70f4-759b-4d5e-9c06-88c00f16f3c1/Participants/v3:9X2vxPDFY2RHSJ1EdMS0RHRksMTg7ldNxdjWbVr9zBjbGjGsSe-aiQ.json"
}

Changes

  • eaf7ad0b9886Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

  • a6a61a29ecddRevision changes
    • info

      added the new optional request property