Create a call

POST

/v1/voice/calls

const call = await bird.voice.calls.create({
  from: "+12025550100",
  to: "+12025550101",
  sequence: {
    id: "vsq_01krdgeqcxet5s7t44vh8rt9mg",
    entry_node_id: "start",
    trigger_data: {},
  },
});
console.log(call.id, call.initial_leg_id, call.sequence?.run_id);

call = client.voice.calls.create(
    from_="+12025550100",
    to="+12025550101",
    sequence={
        "id": "vsq_01krdgeqcxet5s7t44vh8rt9mg",
        "entry_node_id": "start",
        "trigger_data": {},
    },
)
print(call.id, call.initial_leg_id)

call, err := client.Voice.Calls.Create(context.Background(), bird.VoiceCallsCreateParams{
	From: "+12025550100",
	To:   "+12025550101",
	Sequence: bird.CreateVoiceCallSequenceRequest{
		Id:          bird.Ptr("vsq_01krdgeqcxet5s7t44vh8rt9mg"),
		EntryNodeId: "start",
		TriggerData: map[string]any{},
	},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(call.Id, call.InitialLegId)

$call = $bird->voice->calls->create(
    (new CreateVoiceCallRequest())
        ->setFrom('+12025550100')
        ->setTo('+12025550101')
        ->setSequence(
            (new CreateVoiceCallSequenceRequest())
                ->setId('vsq_01krdgeqcxet5s7t44vh8rt9mg')
                ->setEntryNodeId('start')
                ->setTriggerData([]),
        ),
);
echo $call->getId(), ' ', $call->getInitialLegId();

bird voice calls create \
  --from +12025550100 \
  --entry-node-id start \
  --sequence-id vsq_01krdgeqcxet5s7t44vh8rt9mg \
  --trigger-data '{}' \
  --to +12025550101 \
  --idempotency-key "${IDEMPOTENCY_KEY:?Set a fresh key for a new request; reuse it for retries}"

curl -X POST "https://us1.platform.bird.com/v1/voice/calls" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+12025550100",
    "to": "+12025550101",
    "sequence": {
      "id": "vsq_01krdgeqcxet5s7t44vh8rt9mg",
      "entry_node_id": "start",
      "trigger_data": {}
    }
  }'

Respons202

{
  "id": "vcs_01krdgeqcxet5s7t44vh8rt9mg",
  "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
  "initial_leg_id": "vcl_01krdgeqcxet5s7t44vh8rt9mg",
  "direction": "outbound",
  "started_at": null,
  "ended_at": null,
  "live": false,
  "has_recording": false,
  "has_transcript": false,
  "parties": [],
  "sequence": {
    "id": "vsq_01krdgeqcxet5s7t44vh8rt9mg",
    "run_id": "vsr_01krdgeqcxet5s7t44vh8rt9mg"
  }
}

Accepts a real outbound call that runs a voice sequence after the recipient answers, starting at the selected entry node. Supply exactly one of sequence.id, to run the active publication of a saved sequence, or sequence.definition, to run a complete definition once without saving it. Production availability rules and normal calling charges apply. Requires both voice management write and voice calling write permissions and a permitted calling number. Browser users and API keys are supported. Draft and test selectors are not accepted. See the Create Call guide.

An inline definition must pass the same checks as publishing a sequence; the first blocking problem returns 422 with its location under /sequence/definition. Its run executes at most 16 commands, including gather prompts; a call that needs a 17th ends with the call_limit trace error instead of running it. The accepted call's sequence.id is null, because its run belongs to no saved sequence.

Supply sequence trigger data as an explicit object matching the selected entry's configured data schema, or an empty object when no data is needed. The active publication or inline definition, entry node, and trigger data are frozen when the call is accepted. The response contains reserved call and initial-leg IDs. Its null started_at, false live, and empty parties describe the acceptance snapshot. Acceptance does not guarantee that dialing starts or that call and leg reads become available. A call that fails or is canceled before registration might never appear in those reads. Read progress in the sequence's Runs tab in the dashboard. Once the initial leg is registered, use its initial_leg_id with GET /v1/voice/legs/{leg_id} to inspect the telephone outcome; that read requires voice read permission.

Idempotency is optional. Without an Idempotency-Key header, each request accepts a new call attempt. To protect retries, supply a key on the first attempt and reuse it for the same intended call. Requests are limited to 128 KiB. The same idempotency key and exact request bytes replay the original acceptance snapshot for three hours. Changed requests return 409. Authorization and calling-number permission are checked on every request, including replays. Replays include the Idempotency-Replay header with value true.

Payload Permintaan

from

string

wajib

Calling number that this workspace is permitted to present.

to

string

wajib

Recipient number in canonical E.164 form.

ringing_timeout_seconds

integer

Maximum ringing time for the original dialing attempt, shared across routing candidates.

sequence

wajib

Supply exactly one of id, to run a saved sequence's active publication, or definition, to run a sequence once without saving it.

Tampilkan parameter turunan

Payload Respons

id

string

wajib

Unique identifier for this call, shared by every leg that belongs to it.

workspace_id

string

wajib

initial_leg_id

string

wajib

The initial leg identity. For an accepted outbound call, this identity is reserved before the leg starts.

direction

string

wajib

Direction of the initial leg.

started_at

nullable string

wajib

When the initial leg started. null in the acceptance snapshot returned by call creation.

ended_at

nullable string

When the call's last leg ended. null while any leg is still in progress. Recordings and transcripts can still arrive after this instant, so it does not mean the call is finished being written.

live

boolean

wajib

Whether any leg in the call is still held live. A leg stays live until its end is recorded or, when no end is observed, until its liveness window expires, so this can remain true briefly after a disconnect. false covers the interval between a leg ending and its settlement being confirmed, and says nothing about whether transcription has finished.

has_recording

boolean

wajib

Whether the call ever produced a recording. It stays true for the life of the call, so it records that a recording was made rather than promising one can still be fetched.

has_transcript

boolean

wajib

Whether the call ever produced a transcript. A failed transcription attempt does not set it, and a later failure does not clear it.

parties

array of object

wajib

The distinct participant observations the call's legs recorded, for display beside the call. The length is not a count of people and not a reconstruction of the leg graph.

Tampilkan atribut turunan

sequence

object

Sequence and run accepted for this outbound call. Present in the immutable acceptance snapshot returned by call creation. Current call detail and list reads omit this property, including for calls created from a sequence.

Tampilkan atribut turunan

sequence.id

nullable string

wajib

Voice sequence selected for this call. Null for a call that ran an inline definition.

sequence.run_id

string

wajib

Run created from the sequence's frozen publication or the call's inline definition.

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.

Voice sequences

const call = await bird.voice.calls.create({
  from: "+12025550100",
  to: "+12025550101",
  sequence: {
    id: "vsq_01krdgeqcxet5s7t44vh8rt9mg",
    entry_node_id: "start",
    trigger_data: {},
  },
});
console.log(call.id, call.initial_leg_id, call.sequence?.run_id);

call = client.voice.calls.create(
    from_="+12025550100",
    to="+12025550101",
    sequence={
        "id": "vsq_01krdgeqcxet5s7t44vh8rt9mg",
        "entry_node_id": "start",
        "trigger_data": {},
    },
)
print(call.id, call.initial_leg_id)

call, err := client.Voice.Calls.Create(context.Background(), bird.VoiceCallsCreateParams{
	From: "+12025550100",
	To:   "+12025550101",
	Sequence: bird.CreateVoiceCallSequenceRequest{
		Id:          bird.Ptr("vsq_01krdgeqcxet5s7t44vh8rt9mg"),
		EntryNodeId: "start",
		TriggerData: map[string]any{},
	},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(call.Id, call.InitialLegId)

$call = $bird->voice->calls->create(
    (new CreateVoiceCallRequest())
        ->setFrom('+12025550100')
        ->setTo('+12025550101')
        ->setSequence(
            (new CreateVoiceCallSequenceRequest())
                ->setId('vsq_01krdgeqcxet5s7t44vh8rt9mg')
                ->setEntryNodeId('start')
                ->setTriggerData([]),
        ),
);
echo $call->getId(), ' ', $call->getInitialLegId();

bird voice calls create \
  --from +12025550100 \
  --entry-node-id start \
  --sequence-id vsq_01krdgeqcxet5s7t44vh8rt9mg \
  --trigger-data '{}' \
  --to +12025550101 \
  --idempotency-key "${IDEMPOTENCY_KEY:?Set a fresh key for a new request; reuse it for retries}"

curl -X POST "https://us1.platform.bird.com/v1/voice/calls" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+12025550100",
    "to": "+12025550101",
    "sequence": {
      "id": "vsq_01krdgeqcxet5s7t44vh8rt9mg",
      "entry_node_id": "start",
      "trigger_data": {}
    }
  }'

Respons202

{
  "id": "vcs_01krdgeqcxet5s7t44vh8rt9mg",
  "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
  "initial_leg_id": "vcl_01krdgeqcxet5s7t44vh8rt9mg",
  "direction": "outbound",
  "started_at": null,
  "ended_at": null,
  "live": false,
  "has_recording": false,
  "has_transcript": false,
  "parties": [],
  "sequence": {
    "id": "vsq_01krdgeqcxet5s7t44vh8rt9mg",
    "run_id": "vsr_01krdgeqcxet5s7t44vh8rt9mg"
  }
}

Create a call

Payload Permintaan

Payload Respons

Sumber daya terkait