SIP

The sip resource connects phone and SIP calls to rooms. For inbound, provision numbers and bind them to a room with a routing rule. For outbound, place a call through a routing rule or gateway.

Phone numbers

Provisioning numbers also creates their inbound and outbound gateways. For a full walkthrough of acquiring and configuring numbers, see Handling Inbound Calls.

Node.js

await client.sip.phoneNumbers.create({
  name: "Support line",
  phoneNumbers: ["+14155550100"],
  inbound: { sipRegion: "us002" },
  outbound: { address: "sip.telnyx.com:5061", sipRegion: "us002" },
});

Go

client.SIP.PhoneNumbers.Create(ctx, videosdk.CreatePhoneNumbersParams{
	Name:         "Support line",
	PhoneNumbers: []string{"+14155550100"},
	Inbound:      videosdk.PhoneNumberInboundConfig{SIPRegion: videosdk.SIPRegionUS002},
	Outbound:     videosdk.PhoneNumberOutboundConfig{Address: "sip.telnyx.com:5061", SIPRegion: videosdk.SIPRegionUS002},
})

Rust

client.sip().phone_numbers().create(videosdk::CreatePhoneNumbersParams {
    name: "Support line".into(),
    phone_numbers: vec!["+14155550100".into()],
    inbound: videosdk::PhoneNumberInboundConfig { sip_region: videosdk::SipRegion::US002 },
    outbound: videosdk::PhoneNumberOutboundConfig {
        address: "sip.telnyx.com:5061".into(),
        sip_region: videosdk::SipRegion::US002,
        auth: None,
        transport: None,
    },
    is_shared: None,
    media_encryption: None,
}).await?;

Phone numbers also support list, get, detach, updateGateway, and release.

Routing rules

Bind provisioned numbers to a destination room. rule is either a fixed room (direct) or a new room per call (individual).

Node.js

await client.sip.routingRules.create({
  name: "inbound → support",
  type: "inbound",
  phoneNumbers: ["+14155550100"],
  rule: { type: "direct", roomId: "support-line" },
});

Go

client.SIP.RoutingRules.Create(ctx, videosdk.CreateRoutingRuleParams{
	Name:         "inbound → support",
	Type:         videosdk.SIPInbound,
	PhoneNumbers: []string{"+14155550100"},
	Rule:         &videosdk.RoutingRuleTarget{Type: videosdk.RoutingRuleDirect, RoomID: "support-line"},
})

Rust

client.sip().routing_rules().create(videosdk::CreateRoutingRuleParams {
    name: "inbound → support".into(),
    direction: Some(videosdk::SipDirection::INBOUND),
    phone_numbers: vec!["+14155550100".into()],
    rule: Some(videosdk::RoutingRuleTarget::Direct {
        room_id: "support-line".into(),
        pin: None,
    }),
    ..Default::default()
}).await?;

Routing rules also support list, get, update, and delete.

Calls

Place, transfer, switch rooms, and end calls. For managing live calls in depth, see Handling Calls.

Node.js

const call = await client.sip.calls.create({
  routingRuleId: "rr_1",
  callTo: "+14155550123",
  callFrom: "+14155550100",
});

await client.sip.calls.transfer(call.id, { to: "+14155550199" });
await client.sip.calls.switchRoom(call.id, { roomId: "escalation" });
await client.sip.calls.end(call.id);

Go

call, err := client.SIP.Calls.Create(ctx, videosdk.CreateSIPCallParams{
	RoutingRuleID: "rr_1",
	CallTo:        "+14155550123",
	CallFrom:      "+14155550100",
})

client.SIP.Calls.Transfer(ctx, call.ID, videosdk.TransferSIPCallParams{To: "+14155550199"})
client.SIP.Calls.SwitchRoom(ctx, call.ID, videosdk.SwitchRoomParams{RoomID: "escalation"})
client.SIP.Calls.End(ctx, call.ID)

Rust

let call = client.sip().calls().create(videosdk::CreateSipCallParams {
    routing_rule_id: Some("rr_1".into()),
    call_to: "+14155550123".into(),
    call_from: Some("+14155550100".into()),
    ..Default::default()
}).await?;

client.sip().calls().transfer(&call.id, videosdk::TransferSipCallParams {
    to: Some("+14155550199".into()),
    ..Default::default()
}).await?;
client.sip().calls().switch_room(&call.id, videosdk::SwitchRoomParams {
    room_id: "escalation".into(),
    ..Default::default()
}).await?;
client.sip().calls().end(&call.id).await?;

Calls also support list and get.

Trunks

A trunk is a SIP connection: inbound receives calls for a set of numbers, and outbound places calls to a SIP host. Each sub-resource has full create, list, get, update, and delete.

For end-to-end setup, see Handling Inbound Calls and Making Outbound Calls.

Node.js

const inbound = await client.sip.trunks.inbound.create({
  name: "Support inbound",
  numbers: ["+14155550100"],
});

const outbound = await client.sip.trunks.outbound.create({
  name: "Telnyx outbound",
  address: "sip.telnyx.com",
  numbers: ["+14155550100"],
});

await client.sip.trunks.inbound.list();
await client.sip.trunks.outbound.delete(outbound.id);

Go

inbound, err := client.SIP.Trunks.Inbound.Create(ctx, videosdk.CreateInboundTrunkParams{
	Name:    "Support inbound",
	Numbers: []string{"+14155550100"},
})

outbound, err := client.SIP.Trunks.Outbound.Create(ctx, videosdk.CreateOutboundTrunkParams{
	Name:    "Telnyx outbound",
	Address: "sip.telnyx.com",
	Numbers: []string{"+14155550100"},
})

client.SIP.Trunks.Inbound.List(ctx, videosdk.SIPTrunkListParams{})
client.SIP.Trunks.Outbound.Delete(ctx, outbound.ID)

Rust

let inbound = client.sip().trunks().inbound().create(videosdk::CreateInboundTrunkParams {
    name: "Support inbound".into(),
    numbers: vec!["+14155550100".into()],
    ..Default::default()
}).await?;

let outbound = client.sip().trunks().outbound().create(videosdk::CreateOutboundTrunkParams {
    name: "Telnyx outbound".into(),
    address: "sip.telnyx.com".into(),
    numbers: vec!["+14155550100".into()],
    ..Default::default()
}).await?;

client.sip().trunks().inbound().list(videosdk::SipTrunkListParams::default()).await?;
client.sip().trunks().outbound().delete(&outbound.id).await?;

Webhooks

Subscribe to call-lifecycle events (call-started, call-answered, call-hangup, and more).

Node.js

await client.sip.webhooks.create({
  url: "https://example.com/hook",
  events: ["call-started", "call-hangup"],
});

Go

client.SIP.Webhooks.Create(ctx, videosdk.CreateSIPWebhookParams{
	URL:    "https://example.com/hook",
	Events: []videosdk.SIPWebhookEvent{videosdk.SIPWebhookCallStarted, videosdk.SIPWebhookCallHangup},
})

Rust

client.sip().webhooks().create(videosdk::CreateSipWebhookParams {
    url: "https://example.com/hook".into(),
    events: vec![videosdk::SipWebhookEvent::CALL_STARTED, videosdk::SipWebhookEvent::CALL_HANGUP],
}).await?;

Webhooks also support list, get, update, and delete.

The call object

Returned by sip.calls.create, get, list, transfer, switchRoom, and end.

Field	Type	Description
id	string	Unique call id.
type	string	Direction (inbound or outbound).
status	string	Call lifecycle status (ringing, answered, ended, …).
from	string	Source number.
to	string	Destination number.
roomId	string	Destination room id.
sessionId	string	Associated session id.
start	string	Call start time (ISO-8601).
end	string	Call end time, null while ongoing.

The trunk object

Returned by the sip.trunks.inbound.* and sip.trunks.outbound.* methods. address and transport are set for outbound trunks only.

Field	Type	Description
id	string	Unique trunk id.
name	string	Display name.
numbers	string[]	E.164 numbers handled by this trunk.
address	string	SIP host (outbound only), e.g. sip.telnyx.com:5061.
transport	string	SIP transport (udp, tcp, tls), outbound only.
mediaEncryption	string	Media encryption setting.
record	boolean	Whether calls on this trunk are recorded.
geoRegion	string	SIP region (auto, us002, in002, …).

The routing rule object

Returned by sip.routingRules.create, list, get, and update.

Field	Type	Description
id	string	Unique rule id.
name	string	Display name.
type	string	Direction (inbound or outbound).
numbers	string[]	Provisioned numbers bound to this rule.
room	object	Destination room config (type, prefix, id, pin).
agentId	string	Dispatched agent id, if the rule targets an agent.
recording	boolean	Whether matching calls are recorded.
createdAt	string	Creation timestamp (ISO-8601).

The phone number object

sip.phoneNumbers.list and get return the number wrapped with its inbound and outbound trunks (each a trunk object, or null). The number itself carries:

Field	Type	Description
phoneNumberId	string	Unique number id (pass to release).
e164	string	The number in E.164 format.
countryCode	string	Country code.
provider	string	Underlying telephony provider.
status	string	Provisioning status.
name	string	Display name.

The webhook object

Returned by sip.webhooks.create, list, get, and update.

Field	Type	Description
id	string	Unique webhook id.
url	string	Delivery endpoint URL.
events	string[]	Subscribed events (call-started, call-answered, call-hangup, …).
createdAt	string	Creation timestamp (ISO-8601).
updatedAt	string	Last update timestamp (ISO-8601).