> ## Documentation Index > Fetch the complete documentation index at: https://docs.goyappr.com/llms.txt > Use this file to discover all available pages before exploring further. # Connect your phone system > Send calls from your own PBX, contact center or SIP provider to a Yappr agent, with a SIP username and password from Yappr. Keep the phone system you have and let an agent answer some of its calls: after hours, overflow, an IVR option, a queue. You create a **SIP trunk** in Yappr, Yappr gives you a username and password, and you add them to your phone system as one more SIP trunk. Every call it sends to that trunk is answered by the trunk's agent. No Yappr phone number and no porting. A trunk only brings calls in: it can't be used to place calls, and its agent can't transfer a caller to a person yet (see [transfers](#transfers)). There are two kinds of SIP endpoint. Use a username-and-password trunk unless your platform can't send one (see [platforms](#platforms)). | | Username and password (recommended) | SIP address only | | - | - | - | | What your phone system gets | A username and a password, plus the server to send calls to | One SIP address, `sip:-@yappr-byoc.sip.telnyx.com` | | Who can call the agent | Only a system that has the password | Anyone who has the address | | What you can dial | Any number or extension | The address only | | Changing the secret | [Issue a new password](/api-reference/sip-endpoints/rotate-password); the username stays | Create a new endpoint, then delete the old one | | API | `auth_mode: "credentials"` | `auth_mode: "uri"` (the default) | ## Create the trunk * **Dashboard:** **Phone Numbers → SIP Endpoints → Create SIP Endpoint**, choose **Username and password**, name it and pick the agent that answers. Only workspace owners and admins can create one. * **API:** [POST /sip-endpoints](/api-reference/sip-endpoints/create) with `"auth_mode": "credentials"`, using a key with `sip_endpoints:manage`. If username-and-password trunks aren't switched on for your workspace, the dashboard offers only SIP addresses and the API answers `403 SIP_TRUNKS_NOT_ENABLED`: ask Yappr support to switch them on. [GET /sip-endpoints/status](/api-reference/sip-endpoints/status) tells you whether you can create one right now. The password is shown **once**, right after you create the trunk. Copy it into your phone system, or a password manager, before you close the panel: neither the dashboard nor the API can show it again. If it is lost, [issue a new one](/api-reference/sip-endpoints/rotate-password). Each trunk answers with one agent. To send calls to different agents, create a trunk for each. Each trunk takes **2 calls at once** unless you change its limit (`max_concurrent_calls`, 1 to 8). One call more is refused with `486 Busy Here`, so your phone system can try its next route. If your workspace's inbound [calling hours](/api-reference/call-windows/get) are switched on (`inbound_enabled`), they apply to trunk calls too: outside them, every call to the trunk is refused with `603 Decline`, including after-hours calls your phone system sends to the agent. If the trunk takes after-hours calls, widen those hours or switch inbound calling hours off. ## What to enter in your phone system | Setting | Value | | - | - | | SIP server (proxy, registrar, host) | From Israel or Europe, `sip.telnyx.eu`: it is the closest. Elsewhere, for example in the US, `sip.telnyx.com`. All three servers (`sip.telnyx.eu`, `sip.telnyx.com`, `sip.telnyx.me`) take the same username and password, so another one makes a backup route. | | Transport and port | **TLS on port 5061** (recommended; TLS 1.2 or 1.3). TCP on 5060 and UDP on 5060 also work. | | Username (authentication ID, auth user) | The trunk's username: `yp` followed by 14 lowercase letters and digits. | | Password (secret) | The password shown when you created the trunk: 32 letters and digits, no symbols. | | Realm, if your system asks | The server name you send to, for example `sip.telnyx.eu`. | | Registration and keep-alives | **Recommended.** Over TLS or TCP, register the trunk or send keep-alives (SIP `OPTIONS`) every 30 seconds or less: either keeps the connection open. Over UDP behind NAT or a firewall, send keep-alives every 30 seconds or less even if your system registers, because a registration is refreshed only every few minutes. Otherwise the agent's hang-up may not reach your system (see [register, or send keep-alives](#register-or-send-keep-alives)). | | Codecs | Put G.711 (µ-law or A-law) first: the agent's audio is G.711, so it needs no conversion. G.722, G.729 and Opus also work; G.729 costs some sound quality. | | SRTP (media encryption) | Off, or **mandatory** (RTP/SAVP, keys in the SDP). Never "optional", "best effort" or "optimistic": that call fails with `488 Not Acceptable Here`. | | Number dialled | Any number or extension, for example `1001` or `support`. Whatever you dial (except an emergency number, see below), the call reaches the trunk's agent: a trunk doesn't pass calls on to the phone network, or to the agent of a Yappr number you dial. What you dial is recorded as the number called, which the dashboard's call log shows; in the API, `to` is `null` for every call that arrives on a SIP endpoint. Yappr keeps only its letters, digits and `+ * # . _ -` (up to 64 characters). If nothing is left, or what is left contains the trunk's username, the number called is recorded as `sip-trunk`. | | Caller ID | The caller's number, in the `From` header or in `P-Asserted-Identity`. When both are sent, `P-Asserted-Identity` is used. Caller names are not passed on. If your system sends only the trunk's username as the `From` user (a common default), Yappr records the call with no caller number: the API's `from` is `null`, and the dashboard's call log shows **Unknown caller**. So make sure one of the two carries the caller's number. | | Simultaneous calls (channels) | The trunk's `max_concurrent_calls`: 2 unless you changed it. Set the same limit on this trunk in your system, so that it sends an extra call to its next route instead. | | No-answer timeout | About 20 seconds, with failover to your next route. If Yappr can't be reached, the call keeps ringing until your system gives up. | The server, backups, transports and registration are also in every trunk's `sip_connection` in the API. Keep emergency numbers on your regular phone lines, out of every route that uses this trunk. Telnyx handles emergency numbers itself and never hands those calls to Yappr, so no agent answers them, and Yappr can't tell you whether such a call reaches emergency services. ### Register, or send keep-alives When the agent ends a call, Yappr's hang-up has to travel back to your phone system: over TLS or TCP on the connection your system opened, over UDP through your router or firewall. The server keeps a quiet connection open, but some phone systems close their own after about 30 seconds without traffic, and routers and firewalls forget a quiet UDP path, some within a minute. Once that path has closed, the hang-up never arrives, and the caller stays on a silent line until they hang up themselves. To keep the path open: * **Over TLS or TCP:** register the trunk with its username and password, or send keep-alives every 30 seconds or less. Either keeps the connection open. * **Over UDP behind NAT or a firewall:** send keep-alives every 30 seconds or less, even if your system registers. A registration is refreshed only every few minutes, too seldom to keep a UDP path open. Keep-alives are SIP `OPTIONS` requests, often called *qualify* or *heartbeat* (in Asterisk, `qualify_frequency`; in FreePBX, **Qualify Frequency**; in FreeSWITCH, `ping`). If a firewall in front of your system only lets known traffic in, also allow SIP from the server's addresses (see [firewalls](#firewalls)). Then check it once: make a test call of at least two minutes, let the agent end it, and make sure your system hangs up too. A shorter call can end correctly even with no keep-alives at all. ### When the same system also uses another Telnyx trunk If the same phone system or IP address also sends calls to another Telnyx trunk, or you send from a cloud platform whose addresses other customers share, add the header `X-Telnyx-Username: ` to this trunk's calls, so that each call is matched to this trunk. If your system can't add headers, put the username in the user part of its `Contact` header instead. Plivo, Sinch and Infobip send calls from addresses other customers share, and document no way to do either. If another Telnyx customer's trunk is tied to one of those addresses, a call can land on that trunk instead of reaching your agent. Yappr hasn't tested this yet, so ask Yappr support to test your route with you before you send real calls over it. ### TLS certificates Most phone systems trust the server's certificate out of the box. If yours only trusts root certificates you upload (3CX does, for example), upload both: * **DigiCert Global Root G2**, which signs the `sip.telnyx.com` and `sip.telnyx.eu` certificates today; * **ISRG Root X1** (Let's Encrypt), which signs `sip.telnyx.me`, and will sign `sip.telnyx.eu` and `sip.telnyx.com` too once Telnyx moves them on 12 and 13 November 2026. Take ISRG Root X1 from [letsencrypt.org/certificates](https://letsencrypt.org/certificates/) in its **self-signed** version, not a cross-signed one. Telnyx suggests adding Let's Encrypt's other current self-signed roots as well: ISRG Root X2, ISRG Root YE and ISRG Root YR. ### Firewalls If a firewall in front of your phone system only lets known traffic through, allow: * **SIP** to and from the server you send to (on its side, TLS 5061, TCP or UDP 5060\): the agent's hang-up comes from it. `sip.telnyx.com` is 192.76.120.10 and 64.16.250.10, `sip.telnyx.eu` is 185.246.41.140 and 185.246.41.141, and `sip.telnyx.me` is 185.246.42.128 and 185.246.42.129. * **Media (RTP)** to and from Telnyx's media networks below, which use UDP ports 16384 to 32768 on their side. The media can come from a different address than the SIP server. ```text theme={null} 36.255.198.128/25 50.114.136.128/25 50.114.144.0/21 64.16.226.0/24 64.16.227.0/24 64.16.228.0/24 64.16.229.0/24 64.16.230.0/24 64.16.248.0/24 64.16.249.0/24 103.115.244.128/25 103.115.247.0/24 185.246.41.128/25 185.246.42.128/28 ``` Telnyx publishes the current addresses at [sip.telnyx.com](https://sip.telnyx.com/), and as JSON at `https://sip.telnyx.com/voice.json`. ## What your phone system hears back | SIP response | When | | - | - | | `180 Ringing`, then `200 OK` | The agent answers. | | `403 Forbidden` | Wrong username or password, or the trunk was deleted. The call never reaches Yappr, so it is not in your call log. | | `480 Temporarily Unavailable` | The call rang for about 20 seconds and the agent couldn't be connected, or Yappr couldn't send its usual refusal (`486` or `603`). Your system can retry or try another route. | | `486 Busy Here` | The trunk already has as many calls as its `max_concurrent_calls` (2 unless you changed it), or Yappr is at its limit of simultaneous calls right now. Your system can retry or try another route. | | `488 Not Acceptable Here` | SRTP was offered as optional. Turn it off or make it mandatory. | | `603 Decline` | The trunk or its agent is switched off, the call is outside your workspace's inbound [calling hours](/api-reference/call-windows/get) (when they are switched on), the workspace is out of credit, or Yappr could not take the call. | | Ringing, and nothing more | Yappr can't be reached. Your system's no-answer timeout ends the call. | Answered calls use your workspace's credit, like other calls to your agents. A call refused before it is answered costs nothing. Before you switch a trunk off or delete it, re-route its calls in your phone system. A switched-off trunk still looks available to your system (it can still register), but every call to it is refused with `603 Decline`, and not every system tries its next route after that. ## Transfers Transfers to a person aren't available yet on calls that arrive over a SIP trunk. If the agent tries one, nothing is dialled: the caller stays with the agent, which is told that this call can't be transferred, and the call's events record a `transfer_failed` with `error_code` `UNAVAILABLE_ON_SIP_TRUNK`. If some callers must be able to reach a person, handle it in your phone system: send the trunk only calls the agent can finish, or forward the calls that may need a person to one of your workspace's [Yappr phone numbers](/api-reference/phone-numbers/purchase) over the phone network instead, where transfers work. ## Change the password [Issue a new password](/api-reference/sip-endpoints/rotate-password) in the dashboard (the trunk's **Change password**, owners and admins) or with the API. The old one stops working within seconds, and calls already in progress are not dropped. If your phone system registers, enter the new password before its next registration refresh, or that refresh fails. To switch with no gap at all, create a second trunk on the same agent, move your phone system to it, then delete the old trunk. ## Platforms These platforms document that they answer a username-and-password challenge on the calls they send, so they can use a trunk. The rows name `sip.telnyx.com`; from Israel or Europe, enter `sip.telnyx.eu` instead, as the server and as the realm. | Platform | Where the username and password go | | - | - | | 3CX v20, self-hosted | A SIP trunk from the **Generic VoIP Provider** template: Authentication ID and Authentication Password, server `sip.telnyx.com`. 3CX can't add headers; where you'd need `X-Telnyx-Username`, set **Contact: User Part** (Outbound Parameters) to the Authentication ID. 3CX SMB and systems hosted by 3CX accept only 3CX-tested provider templates, so they can't add this trunk. | | FreePBX, Asterisk | A PJSIP trunk: Username and Secret, Authentication **Outbound**, SIP Server `sip.telnyx.com`, port 5061 with TLS, and Registration **Send**. Over UDP behind NAT or a firewall, or with Registration **None**, also set **Qualify Frequency** (pjsip Settings → Advanced; 60 by default) to 30 seconds or less. In Asterisk, `outbound_auth` on the endpoint and `qualify_frequency` on the AOR; `contact_user` can carry the username. | | FreeSWITCH, FusionPBX | A gateway with `username`, `password` and `proxy`. If you set `realm`, use the server name. `extension-in-contact=true` puts the username in the `Contact` header. Set `ping` to 30 seconds or less; over TLS or TCP, setting `register` to `true` is enough instead. | | VICIdial | **Admin → Carriers**: an Account Entry with host `sip.telnyx.com`, username and password. Add `qualify=yes` and `qualifyfreq=25` to the Account Entry, for a keep-alive every 25 seconds (the default is every 60). Over TLS or TCP, a Registration String that registers is enough instead. | | Issabel | A SIP or PJSIP trunk with the username, secret and host `sip.telnyx.com`. Add a keep-alive every 30 seconds or less: `qualify=yes` and `qualifyfreq=25` in a SIP trunk's Peer details, or `qualify_frequency=25` on a PJSIP trunk. Over TLS or TCP, a registration string is enough instead. | | Yeastar | A **Register Trunk** with host `sip.telnyx.com`, username and password, over TLS: it registers, which keeps the connection open. Over UDP, also turn on **Qualify**; Yeastar doesn't document how often it sends, so TLS is the safer choice. | | Grandstream UCM | A **Register SIP Trunk** with host `sip.telnyx.com`, username, authentication ID and password. Turn on **Enable Heartbeat Detection** (Advanced Settings) with **Heartbeat Frequency** at 30 seconds or less (60 by default). Over TLS or TCP, turning on **Need Registration** (off by default) is enough instead. | | Avaya IP Office | A SIP line, with the username and password under **SIP Credentials**. | | Xorcom CompletePBX | A SIP trunk with the username and secret. | | Cisco CUBE | `authentication username password realm ` under `sip-ua`, with the realm set to the server you send to. A SIP profile can add `X-Telnyx-Username`. | | AudioCodes Mediant | An **Accounts** entry (served: your PBX; serving: the trunk) with the username and password; **Register** **Regular** also registers it (the default, **No**, only answers the challenge). **Contact User** can carry the username. Or, on the IP Group toward the trunk, set **Authentication Mode** to **SBC as Client**, with the username and password in **Username As Client** and **Password As Client**. Without a matching Accounts entry, the default mode, **User Authenticates**, passes the challenge on to your PBX. | | Ribbon SBC | SBC Edge: a **Remote Authorization** entry, assigned to the SIP Server Table. | | Oracle SBC | An `auth-attribute` on the session agent, with the realm (the server name), username and password. | | Twilio Programmable Voice | `sip:support@sip.telnyx.com;transport=tls?X-Telnyx-Username=...`, with the trunk's username in both places. Twilio sends from addresses that other customers share, so keep the `X-Telnyx-Username` header. | | Plivo | XML `` with `sipAuthUsername` and `sipAuthPassword`, or a SIP trunking origination URI with authentication on. Plivo's XML can't send `X-Telnyx-Username`, and its SIP trunking documents no way to, so [test it with Yappr support first](#when-the-same-system-also-uses-another-telnyx-trunk). | | SignalWire | cXML ``, or SWML `connect` with `username` and `password`. In SWML, set `encryption` to `mandatory` or `forbidden`: its default, `optional`, fails. SignalWire's addresses are shared too: add `?X-Telnyx-Username=` to the cXML address, or the header in SWML's `headers`. | | Sinch Elastic SIP Trunking | A **Credential** with the username and password, assigned to the SIP endpoint. Sinch documents no way to send `X-Telnyx-Username`, so [test it with Yappr support first](#when-the-same-system-also-uses-another-telnyx-trunk). | | Infobip | A SIP trunk of type **Authenticated**, over TLS (the only transport it allows there). Infobip documents no way to send `X-Telnyx-Username`, so [test it with Yappr support first](#when-the-same-system-also-uses-another-telnyx-trunk). | | Genesys Cloud BYOC Cloud | An external trunk with **Digest Authentication** on: Realm (the server you send to), User Name and Password. Also add the custom SIP header `X-Telnyx-Username` with the username. | Whatever the platform, keep the path open where it offers a setting for it, as [described above](#register-or-send-keep-alives): over UDP behind NAT or a firewall, that means keep-alives every 30 seconds or less. Then check with a test call of at least two minutes that the agent ends. These **can't** answer that challenge on the calls they send: * **Twilio Elastic SIP Trunking** (origination). Use Twilio Programmable Voice instead: point the number at TwiML with the `` above. * **Vonage**, **Bandwidth**, **Five9**, **Amazon Connect**, **RingCentral**, **Zendesk Talk**. * **Calls routed by your own Telnyx account** (Call Control, TeXML or call forwarding): Telnyx doesn't sign in to a trunk with its username and password when it routes a call there. Send those numbers to a [SIP address endpoint](/api-reference/sip-endpoints/create#sip-address-endpoint) instead. * **Microsoft Teams Direct Routing** and **Zoom Phone**, except through your own SBC (AudioCodes, Ribbon, Oracle or Cisco CUBE above), which then sends the calls to the trunk. For any other platform: * add the trunk on your own PBX and route the calls through it; * or forward the calls to a [Yappr phone number](/api-reference/phone-numbers/purchase); * or, if it can send calls to a plain SIP address, use a SIP address endpoint (`auth_mode: "uri"`), whose address is its only secret. ## Security * A call needs the trunk's username and password. A wrong one is refused before the call reaches Yappr. * The password is shown only when you create the trunk or issue a new one. Yappr does not keep a copy. * Calls sent to a trunk reach its agent and no one else, and a trunk can't be used to place calls. Emergency numbers never reach the agent: keep them off the trunk (see the warning above). * Even with a leaked password, a trunk takes no more calls at once than its `max_concurrent_calls`. * Only workspace owners and admins can create, change or delete a trunk, or issue a new password, in the dashboard. API keys need `sip_endpoints:manage`. A key with `sip_endpoints:read` alone lists endpoints without passwords, without trunk usernames (`sip_username` is `null`) and without SIP addresses (`slug` and `sip_uri` are `null`). * Your phone system sets the caller's number, so Yappr does not use it to recognize returning callers (lead memory) on these calls. * If the password may have leaked, issue a new one. To stop the trunk for a while, turn it off (`is_active: false`); to stop it for good, delete it. Either way, re-route its calls in your phone system first. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.