Telephony and SBC
This page is for partners and for the administrators of the SIP trunk and the session border controller (SBC) connected to Graia CCaaS. The SIP trace shows where a call failed: find the first leg that failed and the side that sent the error, then fix it there. Graia support can help when it isn't clear.
Graia CCaaS has no connection to Microsoft Teams or to any other phone system your agents use. When agents answer calls in an external voice application, such as Teams or a desk phone, Graia CCaaS calls the agent's phone number through your SBC or carrier, and your own setup delivers the call from there. Problems in your own phone system behind your SBC are for your telephony team. The call's path in Graia CCaaS can still be involved, so check the SIP trace and example calls before deciding where the fault is: see Agents who answer in an external voice application.
Start with the SIP trace
Before you decide where the fault is, find out which leg failed first and who sent the error. Every call to an agent and every outbound call has its own SIP signalling. The response code and the sender tell you where to start looking, but they don't prove the cause on their own: a device can send an error because something further along failed.
- Your SBC or carrier logs: look for the INVITE and the final response, and note the time, the direction and who sent it.
- Graia support: can look up the call in the platform's SIP traces and send you the call flow and the packet capture, for example to forward to your carrier or SBC provider. Give the date and exact time with the time zone, the caller number, the channel number and the agent.
- Portal: Conversation History (Historical Reports › Conversations) shows every call that reached Graia CCaaS, including calls that never reached an agent. Task History (Historical Reports › Tasks) shows every call offered to an agent, even one the agent never got, because a task is created for the agent when the call is offered. Use them to find examples with exact times.
Graia CCaaS keeps SIP traces for about 10 days. After that, a call can no longer be investigated at signalling level. Reproduce and report problems while they're fresh.
SIP responses seen in support cases
A response code is a lead, not proof of the cause. Use it together with who sent it, when, and what happened before it in the trace.
| Response | Who can send it | What it can mean | What to check |
|---|---|---|---|
403 Forbidden | Either side | The request isn't accepted: an unknown source, authentication or tenant identification that doesn't match, or the agent's number isn't set up behind your SBC. | Who sent it; allowed sources and credentials on both sides; the agent's number in your own phone system. |
404 Not Found | Usually your SBC or carrier | Your SBC or carrier has no route for the call or the agent leg. Rarely seen. | Outbound routing on your SBC. |
408 Request Timeout | Either side | No final response arrived in time. There may have been provisional responses before it. | The messages before it and which hop stopped responding. Is the far end up? Are the SIP ports open? Is it sending to the right address? |
480 Temporarily Unavailable | Either side, usually the carrier or your SBC | The carrier or SBC bounced the call, or the agent's voice application is unreachable. | Carrier status; SBC logs for the rejected INVITE; the agent's voice application. |
486 Busy Here | Either side | The destination is busy. Inbound from Graia CCaaS, it usually means the called number doesn't match any channel number. | Whether the destination was busy; the called number against the channel numbers. |
487 Request Terminated | Either side | The call was cancelled before it was answered, for example by the RONA timeout on an agent leg, or because the caller hung up. | What cancelled the call and when; for agent legs, why the agent didn't answer in time. |
488 Not Acceptable Here | Either side | The media offer (codecs or other audio settings) wasn't accepted. | The codecs and media settings offered and expected on both sides. |
500 Server Internal Error | Either side | An internal fault on the device that sent it, or on something behind it. | Who sent it; that device's health and logs. |
502 Bad Gateway | Either side | A gateway or proxy couldn't complete the call towards the next hop. For tenants that still use an active and a passive address, the passive address answers this way, but the code alone doesn't prove which address was passive. | Who sent it; that your SBC resends to the other address (see Connection addresses and failover). |
503 Service Unavailable | Either side | The device or something behind it is overloaded, unavailable or out of free channels, for example an SBC with its signalling groups down. | Who sent it; SBC status and signalling groups; channel capacity. |
503 … CAC LIMIT | Your SBC or carrier | The call admission control limit is reached: no free concurrent channels. | Channel capacity (see Calls fail at busy times). |
603 Decline | Either side | The call was declined, for example by the carrier because the caller ID isn't in its allowed ranges, or by the agent in their voice application. | Allowed caller ID ranges at the carrier; whether the agent declined. |
604 Does Not Exist Anywhere | Your SBC or carrier | The agent's number isn't active on the carrier or partner platform. | That the agent's number is activated at the provider. |
All agents go to RONA or calls drop at once
This section is for agents who answer in an external voice application. For agents who answer in the browser, see Agent calls and connection.
When every agent of a team is put into RONA as soon as a call is offered, or calls drop the moment they connect, a common cause is your SBC rejecting the calls to the agents. Graia CCaaS calls each agent through your SBC (the agent leg); if the SBC refuses that INVITE, the agent can't answer and goes to RONA.
Check: find two or three affected calls and look for the final response and its sender in your SBC logs, or ask Graia support for the trace. If the SBC didn't reject the call, or the trace isn't clear, send the examples to Graia support.
Common causes, most frequent first:
- The SBC rejects or doesn't answer the agent leg – a configuration change, a stuck session, signalling groups left down after maintenance, or a node failure. Fix it on the SBC or with your SBC provider; switching to the second SBC node often restores service.
- The SBC still answers OPTIONS but rejects calls – for example with
503while its signalling groups are drained. Because OPTIONS keepalives still succeed, no failover happens. Bring the signalling groups back up. - Channel capacity is exhausted – see Calls fail at busy times.
- Expired or replaced certificates on your SBC – see Certificates on your SBC.
- The carrier, or the provider of your agents' voice application, has an outage – see the next section and Outage at your voice provider.
Who fixes it: when the trace shows your SBC rejecting the calls, your SBC administrator or SBC provider. Graia support can provide traces that show where the rejection comes from.
While the problem lasts, agents can't leave RONA usefully because every new call fails the same way. Consider an emergency workflow with an announcement that you can assign to the affected channels.
No inbound calls reach the contact centre
The carrier or telephony provider has an outage
Callers hear "number doesn't exist", "number not in use" or nothing, and no call appears in Graia CCaaS – not even in the IVR.
Check: ask Graia support whether the calls reached the Graia address at all, including calls that were rejected there. If nothing arrived, the calls stopped before Graia CCaaS: at the carrier, at a number-hosting provider in the chain, or at your SBC. Check your trunk status and your SBC logs.
Fix: if the calls never reached the Graia address, contact your carrier or telephony provider. If they arrived but were rejected, see Calls from your SBC are rejected or get no reply.
Connection addresses and failover
Graia support gives you the SIP connection details for your tenant: the Graia addresses to send calls to, and which transport to use. Configure all the addresses on your SBC, with failover between them.
- Most tenants are active-active. Every address accepts calls, so your SBC can send to any of them.
- Some tenants are still active-passive. Only one address accepts calls at a time. The other answers
502 Bad Gateway, and the roles can swap. Graia is moving all tenants to active-active, so this applies to fewer and fewer tenants.
So that calls work in both cases, set up your SBC to resend the INVITE to the other address when it gets a 502, unless the first INVITE already got a successful response, or the INVITE that got the 502 was already sent to the other address. Without this, inbound calls stop for the whole tenant whenever your SBC sends to the passive address.
Use the same connection details on every system that sends calls to Graia CCaaS: SBCs, PBXs and external voicebots. Don't add addresses that support hasn't given you.
Calls from your SBC are rejected or get no reply
If calls from your SBC fail or its OPTIONS get no reply, for example after you added or replaced an SBC, send Graia support:
- the public IP addresses of all your SBCs
- the Graia address your SBC sends to, and the transport (UDP, TCP or TLS)
- the date and exact time of a few failed calls, with the time zone
- a SIP trace from your SBC, if you have one
The cause can be on either side, for example a new SBC address that isn't set up for your tenant yet, tenant identification or credentials that don't match, or a firewall. Support can tell from the platform's side whether the calls arrived and why they were rejected.
Calls to a number fail with 486 Busy Here or "not available"
The call reaches Graia CCaaS, but the called number (the number in the To header) doesn't match a channel number, so the platform can't route it and answers with 486 Busy Here. Callers hear a busy tone, "not available" or "number not found". A 486 can have other causes too, so check the trace for the called number first.
| Cause | Check | Fix |
|---|---|---|
| The number isn't assigned to any channel. | Search for the number under Voice › Channels. | Add it to a channel, and confirm your carrier routes it to Graia CCaaS. |
| The call was forwarded, and it still carries the originally dialled number. | Compare the called number in the SIP trace with the channel's Phone Number. | Add the dialled number as an alternative number on the channel (see Alternative inbound numbers), or have your carrier send the channel number as the called number. |
The number format differs. For example a double +, a missing country code, or a national format. | Compare the exact digits in the trace with the channel number. | Send numbers in E.164 format (+ and country code). Align your SBC's number manipulation rules so the destination matches the channel number exactly. |
Changes to channels can take up to 30 minutes to apply.
Outbound calls fail or drop immediately
Outbound calls in Graia CCaaS have two legs: the platform first calls the agent (the agent leg), then dials the customer (the customer leg). Either leg can be rejected. The agent typically sees the call window open for a second and close, or the call ring once and drop.
Causes, most frequent first:
- Your SBC rejects the call with an error SIP response. Check the SBC's outbound routing and logs for the rejected INVITE.
- The carrier rejects the caller ID with
603 Decline, because the presented number isn't in the ranges it allows on your trunk. Ask the carrier to allow the number, or change which number you present (see The wrong number is shown). - The carrier rejects the number format. If calls work with
+and the country code but not in national format, ask the carrier to accept both, or dial in international format. - Short or emergency numbers fail. When Use channel number as dialing number is off, the agent leg carries the dialled number as the caller ID (see the header table). Your SBC must then accept an agent-leg call that comes "from" a three-digit number and route it to the agent. Otherwise it rejects it.
- The carrier or trunk provider rejects all calls with
403. Check the trunk registration and whether the provider's IP addresses changed.
If only one agent is affected while others can call, see Agent calls and connection: the cause is most likely on that agent's side rather than on the trunk.
The wrong number is shown
Caller ID, PAI and the "Use channel number as dialing number" setting
Use channel number as dialing number (Administration › Configuration › Voice) decides which number goes in the SIP FROM header of calls the platform places – including the calls to agents on behalf of inbound customers.
- Off:
FROMcarries the original caller (the customer, or the agent for consults). The channel number goes in aP-Asserted-Identityheader. - On:
FROMcarries the channel number on every leg except a consult to an agent.
See the full table of headers per call scenario.
This one setting has visible effects in several places, so test both inbound and outbound calls after changing it:
| Symptom | Likely cause |
|---|---|
| Agents see the channel name or number instead of the caller's number in their voice application. | The setting is on. Turn it off. |
| A third-party call recorder shows the channel number for every call, so you can't search recordings by caller. | The setting is on; the recorder reads the agent leg's FROM. Turn it off, or have the recorder read a custom SIP header. |
A redirect from a workflow to an external voicebot needs the channel number in FROM. | Keep the setting on, and pass the caller number in a custom SIP header. |
A custom PAI header requested from Graia overrides this setting. Whether the receiving phone shows any of these numbers also depends on the carrier.
The caller's number is wrong or hidden
Graia CCaaS shows the number it receives. If incoming calls show a number that isn't the real caller, or a fixed number, your carrier or SBC changed it before the call reached the platform. If forwarded calls to agents' mobiles show "Private number", the carrier on that leg hides the identity. Check the SIP trace: if the platform sent the correct FROM, ask the carrier.
After a carrier moves to E.164 caller numbers, a CRM that stores national-format numbers stops finding customers. Adjust the number transformation rules on your SBC, and test before rolling out.
Calls fail at busy times: 503 CAC limit
At peak times, calls to agents fail and agents go to RONA, while calls wait in queue. Your SBC or trunk returns 503 with a call admission control (CAC) message.
Size your trunk and SBC licences on the highest number of simultaneous calls that actually pass through them: callers waiting in the queue, calls to agents, transfers, consultations, callbacks and campaign calls. Calls to agents who answer in the browser don't go through your SBC. Compare your measured peaks with your trunk's channel limit and with how your carrier and SBC count licensed channels.
Example: if your agents answer in an external voice application, such as Teams or a desk phone, each busy agent can use one channel for the customer's call and one for the call to the agent. If about half of the agents are on a consultation call at the same time, that adds half a channel per agent: about 2.5 concurrent channels per agent. Your own traffic can need more or fewer.
Who fixes it: your carrier or SBC provider, by raising the channel limit or licences.
The IVR doesn't recognise keypresses
Callers press digits but the IVR plays its prompt to the end and takes the default path. If this happens only for callers from one country or one mobile network, a carrier in the chain most likely isn't passing DTMF (or passes it in an unsupported way). Ask that carrier to check DTMF transmission. If it happens for all callers, or the carrier finds nothing, send Graia support example calls (date, exact time, caller's number, channel) so they can check how the keypresses arrived.
Agents who answer in an external voice application
Your SBC's routing, your phone system and the agent's device are your setup, and your telephony team or provider fixes them (see the note at the top of this page). The call's path in Graia CCaaS can still be involved, especially for audio problems, so compare the SIP trace and example calls before deciding where the fault is. Most problems show up as agents going to RONA.
Agents answer in the voice application
Agents answer in their voice application, not in the agent application. The agent application shows the call with only a hang-up button – that's expected. See Answer an inbound call.
If the call doesn't ring in the voice application, check the SIP trace first:
- Your SBC rejected the call with an error SIP response: check the reason in your SBC logs, such as routing, policy, authentication, capacity or a failure further along.
- The call rang (
180) and was cancelled after the RONA timeout (487): the call reached your side. Check the voice application and its settings with your telephony team: notifications, do-not-disturb, call forwarding, and whether a busy agent's second call is rejected. - The platform shows the call answered (
200 OK) but there's no audio: the call was set up, but the audio can still fail on either side. Check your SBC and phone system, and send Graia support example calls.
The agent's phone number doesn't match
The agent's Phone Number in Agents › Agents must match the number your SBC routes to the agent exactly: international format with + and country code, no spaces, no extra characters. A mismatch makes the agent leg fail, or calls close automatically as soon as they arrive.
Outbound calls must start in the agent application
Agents must place calls – including callbacks – from the agent application, not from their voice application. A call started there isn't known to Graia CCaaS: the agent still shows as Available, gets routed calls they can't answer, and goes to RONA. If an agent must call from their voice application, they should set a break first. Routing uses only the agent's state in the agent application.
Transfers to directory contacts also go back out through your SBC. If they fail with a transfer error while transfers to channels work, check your SBC's traces for the rejected INVITE.
Certificates on your SBC
An expired certificate on one of your SBCs makes the calls that go through that SBC fail – for example about one call in three if calls are spread evenly over three SBCs. Agents see the call in the agent application, but it never rings on their side.
- Route all calls to the healthy SBC.
- Renew the certificate on the affected SBC and bring it back.
- Restore the original routing.
When you renew a certificate, make sure it's valid for the name your SBC is reached by (normally a DNS name in the SAN), trusted by the other side, and meets any mutual TLS requirements agreed for your connection. Keep the SBC software up to date.
Outage at your voice provider
When the provider of your agents' voice application has an outage, agents go to RONA and can't take calls. Check the provider's service health. Use a queue timeout with an announcement, or an emergency workflow you can assign to channels, to inform callers.
Connect an SBC or SIP trunk
When you connect a new SBC, carrier or voicebot trunk, ask Graia support for the SIP connection details and check these points. Most onboarding problems come from one of them.
- Addresses and failover: use the addresses and failover settings support gives you (see Connection addresses and failover).
- All source IPs: allow all the platform addresses support gives you on your SBC, firewall and any external voicebot trunk – not only the one you see in your first test.
- Tenant identification: Graia CCaaS recognises which tenant a call belongs to from your connection setup: your SBC's address, a SIP header, SIP credentials or a domain, as agreed with support. If it doesn't match, calls are rejected. This is separate from the called number, which must match a channel number.
- Number format: send numbers in E.164 format (
+and country code). - Codec: G.711 A-law is supported.
- Transport, addresses and ports: use the values Graia support gives you for your tenant. TCP or TLS is usually the more reliable choice for a SIP trunk: over UDP, large SIP messages can be fragmented or switch to TCP mid-call, which can cause intermittent failures. Agree the transport with support before you change it.
- Test number: have a number assigned to a channel before you test inbound calls.
SIP over TLS
For TLS, your SBC must trust the public root certificate authority that signs the platform's certificates. Don't turn off certificate verification. TLS and SIP credentials are separate settings: whether your trunk also uses credentials depends on the connection details support gives you. Test inbound first, then outbound. A 403 Forbidden on the outbound test often means the credentials or the tenant identification don't match.
Related
Was this page helpful?