Skip to main content
Glama

Create SIP trunk

create_sip_trunk
Destructive

Provision a SIP trunk on Vobiz to link your PBX for inbound and outbound calling, with auto-generated domain, digest/IP authentication, and primary/fallback routing.

Instructions

Create a SIP trunk on this Vobiz account: a voice gateway with its own auto-generated SIP domain ({trunk_id}.sip.vobiz.ai), authentication, call limits and outbound routing. Only name is required; Vobiz defaults are transport udp, secure false and cps_limit 2. Authenticate the peer with credential_uuid (digest) and/or ipacl_uuid (source IP), and route outbound calls via primary_uri_uuid with fallback_uri_uuid for failover; create those first with create_trunk_credential, add_ip_acl_entry and create_origination_uri, or attach them later with update_sip_trunk. Returns the full trunk object with any credential fields redacted. Route numbers to the trunk afterwards with update_phone_number (trunk_id). Gated by VOBIZ_ENABLE_PROVISIONING and confirm: true; every call creates another trunk, so after a timeout check list_sip_trunks before retrying.

Input Schema

NameRequiredDescriptionDefault
nameYesDisplay name of the trunk, 1-100 characters.
secureNotrue encrypts media with SRTP (Vobiz default false). Signalling encryption is chosen with transport: tls.
confirmYesMust be true, set only after the user explicitly approved: creating this SIP trunk. If your client supports MCP elicitation, the server asks the user to approve directly and this flag is not relied on; otherwise it is your attestation that the user approved.
cps_limitNoMaximum new calls per second (flood protection), 1-100 (Vobiz default 2). Independent of concurrent_calls_limit; the enforced CPS is the account-level limit.
recordingNotrue records every call on the trunk (Vobiz default false). Required for enable_transcription and recording_webhook_enabled to have any effect.
transportNoSIP signalling transport: udp (Vobiz default), tcp or tls (encrypted signalling).
ipacl_uuidNoUUID of an IP ACL entry (id from list_ip_acl_entries or add_ip_acl_entry) so SIP from that address is accepted without a password. May be set together with credential_uuid.
descriptionNoFree-text note on the trunk's purpose, up to 1000 characters.
webhook_urlNoPublic https URL (max 500 characters) that receives CallInitiated and Hangup events for calls on this trunk; private and local hosts are rejected.
trunk_statusNoenabled or disabled. A disabled trunk keeps its configuration, credentials and routing but handles no calls; Vobiz reports the state as active/inactive on the trunk object.
webhook_methodNoHTTP method for webhook_url deliveries: POST (Vobiz default) or GET.
credential_uuidNoUUID of a trunk credential (id from list_trunk_credentials or create_trunk_credential) for SIP digest authentication of this trunk's peer.
trunk_directionNoWhich calls the trunk carries: inbound (to your numbers), outbound (from your PBX) or both.
primary_uri_uuidNoUUID of the origination URI (id from list_origination_uris or create_origination_uri) that outbound calls are sent to first; failover order is primary, then fallback.
fallback_uri_uuidNoUUID of the origination URI tried when the primary one fails.
inbound_destinationNoDestination inbound calls on this trunk are delivered to (inbound trunks), up to 255 characters, in the form your Vobiz trunk setup uses.
enable_transcriptionNotrue transcribes recordings automatically (Vobiz default false); only effective while recording is true.
concurrent_calls_limitNoMaximum simultaneous calls on the trunk, 1-1000 (Vobiz default 10). Stored on the trunk; the enforced concurrency is the account-level limit.
recording_webhook_enabledNotrue also sends a recording.completed event to webhook_url after each recording is saved (Vobiz default false); needs recording true and a webhook_url.

Output Schema

NameRequiredDescriptionDefault
okNoTrue on success. On a failure the result is isError with ok: false plus `error` (kind), `message`, `retryable` and sometimes `http_status`.
trunkNoThe new trunk; its trunk_id is needed for update_sip_trunk, delete_sip_trunk and update_phone_number.
createdNoTrue when the record was created by this call.
http_statusNoHTTP status Vobiz answered with.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed20 schema fields changedv1.4.2
    • addedInput schema / properties / concurrent_calls_limit / description
      Added value: +"Maximum simultaneous calls on the trunk, 1-1000 (Vobiz default 10). Stored on the trunk; the enforced concurrency is the account-level limit."
    • changedInput schema / properties / confirm / description
      Previous value: -"Must be true, set only after the user explicitly approved: creating this SIP trunk."New value: +"Must be true, set only after the user explicitly approved: creating this SIP trunk. If your client supports MCP elicitation, the server asks the user to approve directly and this flag is not relied on; otherwise it is your attestation that the user approved."
    • addedInput schema / properties / cps_limit / description
      Added value: +"Maximum new calls per second (flood protection), 1-100 (Vobiz default 2). Independent of concurrent_calls_limit; the enforced CPS is the account-level limit."
    • addedInput schema / properties / credential_uuid / description
      Added value: +"UUID of a trunk credential (id from list_trunk_credentials or create_trunk_credential) for SIP digest authentication of this trunk's peer."
    • addedInput schema / properties / description / description
      Added value: +"Free-text note on the trunk's purpose, up to 1000 characters."
    • addedInput schema / properties / enable_transcription / description
      Added value: +"true transcribes recordings automatically (Vobiz default false); only effective while recording is true."
    • addedInput schema / properties / fallback_uri_uuid / description
      Added value: +"UUID of the origination URI tried when the primary one fails."
    • addedInput schema / properties / inbound_destination / description
      Added value: +"Destination inbound calls on this trunk are delivered to (inbound trunks), up to 255 characters, in the form your Vobiz trunk setup uses."
    • addedInput schema / properties / ipacl_uuid / description
      Added value: +"UUID of an IP ACL entry (id from list_ip_acl_entries or add_ip_acl_entry) so SIP from that address is accepted without a password. May be set together with credential_uuid."
    • addedInput schema / properties / name / description
      Added value: +"Display name of the trunk, 1-100 characters."
    • changedInput schema / properties / primary_uri_uuid / description
      Previous value: -"Origination URI used first (failover order: primary, then fallback)."New value: +"UUID of the origination URI (id from list_origination_uris or create_origination_uri) that outbound calls are sent to first; failover order is primary, then fallback."
    • addedInput schema / properties / recording / description
      Added value: +"true records every call on the trunk (Vobiz default false). Required for enable_transcription and recording_webhook_enabled to have any effect."
    • addedInput schema / properties / recording_webhook_enabled / description
      Added value: +"true also sends a recording.completed event to webhook_url after each recording is saved (Vobiz default false); needs recording true and a webhook_url."
    • addedInput schema / properties / secure / description
      Added value: +"true encrypts media with SRTP (Vobiz default false). Signalling encryption is chosen with transport: tls."
    • addedInput schema / properties / transport / description
      Added value: +"SIP signalling transport: udp (Vobiz default), tcp or tls (encrypted signalling)."
    • addedInput schema / properties / trunk_direction / description
      Added value: +"Which calls the trunk carries: inbound (to your numbers), outbound (from your PBX) or both."
    • addedInput schema / properties / trunk_status / description
      Added value: +"enabled or disabled. A disabled trunk keeps its configuration, credentials and routing but handles no calls; Vobiz reports the state as active/inactive on the trunk object."
    • addedInput schema / properties / webhook_method / description
      Added value: +"HTTP method for webhook_url deliveries: POST (Vobiz default) or GET."
    • changedInput schema / properties / webhook_url / description
      Previous value: -"Receives CallInitiated and Hangup events (public https)."New value: +"Public https URL (max 500 characters) that receives CallInitiated and Hangup events for calls on this trunk; private and local hosts are rejected."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": false,
      +  "properties": {
      +    "created": {
      +      "const": true,
      +      "description": "True when the record was created by this call.",
      +      "type": "boolean"
      +    },
      +    "http_status": {
      +      "description": "HTTP status Vobiz answered with.",
      +      "type": "number"
      +    },
      +    "ok": {
      +      "description": "True on success. On a failure the result is isError with ok: false plus `error` (kind), `message`, `retryable` and sometimes `http_status`.",
      +      "type": "boolean"
      +    },
      +    "trunk": {
      +      "additionalProperties": {},
      +      "description": "The new trunk; its trunk_id is needed for update_sip_trunk, delete_sip_trunk and update_phone_number.",
      +      "properties": {
      +        "concurrent_calls_limit": {
      +          "description": "Concurrent-call limit stored on the trunk.",
      +          "type": [
      +            "number",
      +            "null"
      +          ]
      +        },
      +        "cps_limit": {
      +          "description": "Calls-per-second limit stored on the trunk.",
      +          "type": [
      +            "number",
      +            "null"
      +          ]
      +        },
      +        "created_at": {
      +          "description": "Creation timestamp.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "credential_uuid": {
      +          "description": "Attached trunk credential UUID, if any.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "description": {
      +          "description": "Free-text description.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "enable_transcription": {
      +          "description": "True when recordings are transcribed.",
      +          "type": [
      +            "boolean",
      +            "null"
      +          ]
      +        },
      +        "fallback_uri_uuid": {
      +          "description": "Fallback origination URI UUID, if any.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "inbound_destination": {
      +          "description": "Inbound call destination configured on the trunk, if any.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "ipacl_uuid": {
      +          "description": "Attached IP ACL entry UUID, if any.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "name": {
      +          "description": "Trunk name.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "pii_redaction": {
      +          "description": "True when PII is redacted from transcripts.",
      +          "type": [
      +            "boolean",
      +            "null"
      +          ]
      +        },
      +        "primary_uri_uuid": {
      +          "description": "Primary origination URI UUID, if any.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "recording": {
      +          "description": "True when calls on the trunk are recorded.",
      +          "type": [
      +            "boolean",
      +            "null"
      +          ]
      +        },
      +        "recording_webhook_enabled": {
      +          "description": "True when recording.completed events are sent to webhook_url.",
      +          "type": [
      +            "boolean",
      +            "null"
      +          ]
      +        },
      +        "secure": {
      +          "description": "True when media is encrypted with SRTP.",
      +          "type": [
      +            "boolean",
      +            "null"
      +          ]
      +        },
      +        "transport": {
      +          "description": "SIP transport: udp, tcp or tls.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "trunk_direction": {
      +          "description": "inbound, outbound or both.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "trunk_domain": {
      +          "description": "Auto-generated SIP domain of the trunk ({trunk_id}.sip.vobiz.ai).",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "trunk_id": {
      +          "description": "Trunk UUID; use it as trunk_id elsewhere.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "trunk_status": {
      +          "description": "Trunk state as Vobiz reports it (e.g. active or inactive).",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "updated_at": {
      +          "description": "Last-change timestamp.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "webhook_method": {
      +          "description": "HTTP method for webhook_url.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "webhook_url": {
      +          "description": "Webhook receiving CallInitiated and Hangup events, if set.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        }
      +      },
      +      "type": "object"
      +    }
      +  },
      +  "type": "object"
      +}
  2. First observedv1.1.1

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses provisioning gating (VOBIZ_ENABLE_PROVISIONING and confirm: true), non-idempotency ('every call creates another trunk'), retry guidance, and that credential fields are redacted in the response. This adds substantial behavioral context while remaining consistent with annotations like destructiveHint=true and idempotentHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well front-loaded, leading with the core action and then layering prerequisites, defaults, auth, routing, gating, and retry advice. For a 19-parameter creation tool, every sentence contributes operational value without filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is complex, but the description covers the essential workflow: required fields, defaults, dependency ordering, auth options, outbound routing, post-create routing, gating, and retry safety. Since an output schema exists, return-value details do not need fuller explanation beyond the redaction note.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents each parameter in detail. The description still adds cross-parameter meaning, such as authenticating with credential_uuid and/or ipacl_uuid and routing via primary_uri_uuid with fallback_uri_uuid, plus the defaults for transport, secure, and cps_limit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Create a SIP trunk on this Vobiz account', then details the resources it provisions (voice gateway, SIP domain, authentication, call limits, outbound routing). This clearly distinguishes it from siblings like update_sip_trunk, delete_sip_trunk, and create_sip_endpoint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly explains what is required ('Only name is required'), gives defaults, and instructs on prerequisites by naming create_trunk_credential, add_ip_acl_entry, and create_origination_uri. It also covers post-creation routing with update_phone_number and retry behavior after timeouts, naming list_sip_trunks as the check.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools