Concepts and troubleshooting

This page details specific configurations required for integration as well as troubleshooting for common issues.

Telephony network requirements

If your network filters outbound traffic, it must allow outbound traffic for SIP signaling and media streaming.

For SIP signaling, the whole IP range 74.125.88.128/25 (TCP) over port 5672 should be allowed. For a more restrictive firewall rule set, you may restrict SIP signaling to just one or more regionalized GTP SIP servers:

• US region: us.telephony.goog (74.125.88.132)
• EU region: eu.telephony.goog (74.125.88.133)
• APAC region: ap.telephony.goog (74.125.88.134)
• South America region: sa.telephony.goog (74.125.88.135)

For RTP media, you must configure firewall rules to allow traffic destined to the CIDR IP range 74.125.39.0/24. Typically the ports required for media are only 16384-32767 (TCP+UDP), however, this port range may be expanded in the future.

Supported SBC vendors or models

The following table lists the supported SBC vendors or models and firmware versions. Detailed integration instructions for each vendor are linked in the firmware version.

Vendors and models	Firmware versions
AudioCodes VE SBC	v7.40A.500.786
Avaya Session Border Controller for Enterprise	v8.1.3.2-38-22279, v10.2.0.0-86-24077
Oracle E-SBC Acme Packet 3900	SCZ9.3.0 GA (Build 46)
Ribbon Swe Core SBC	v11.01.01R005
Cisco Unified Border Element (CUBE)	v17.15.03a

Note: This table represents the minimum supported firmware versions that have been certified to work with SIP integration. Newer firmware versions that are a part of the same major firmware patch series are also certified.

Supported SBC signaling and media protocols

Signaling Protocol	SIP over TLS
Media	SRTP
Media Encryption	SDES
Media Cipher Suite Supported	AES_CM_128_HMAC_SHA1_80
Media Codecs Supported	G.711 µ-law (PCMU), G.711 A-law (PCMA)

SIP headers

When you set up a conversation profile and phone number, you created a CCAI conversation profile with the sipConfig.createConversationOnTheFly set to true. The conversation ID should be dynamically generated during the SIP INVITE by using the SIP header value of Call-Info or UUI.

The SIP header value points to the Dialogflow endpoint by defining the Google Cloud project ID and conversation ID:

1. The Google Cloud project ID is the project you used when you set up a Google Cloud project.
2. The conversation ID should be dynamically generated by the SBC. The conversation ID must be compliant with the regular expression formula [a-zA-Z][a-zA-Z0-9_-]* with the characters length in range of [3,64]. To dynamically generate the conversation ID, a common pattern is to use the Call-ID value in the SIP INVITE and prefix it with letters to make it compliant with the regular expression as specified previously. For example, if the Call-ID value is 297363723_79131759_799783510, prefixing the Call-ID value with "CID-" would make it compliant with the regular expression [a-zA-Z][a-zA-Z0-9_-]*.

Call-Info SIP header

Insert a custom SIP header called Call-Info in the SIP INVITE to uniquely set the conversation ID:

Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/$PROJECT_ID/conversations/$CONVERSATION_ID>;purpose=Goog-ContactCenter-Conversation

Example: none Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510>;purpose=Goog-ContactCenter-Conversation

UUI SIP header

If setting the custom SIP header Call-Info is not supported, you can configure the UUI (User-to-User) SIP header in the SIP INVITE to pass in the conversation ID.

Use the same data requested in Call-Info with the URL encoded in hex and the purpose set to Goog-ContactCenter-Conversation. The following is an example header, where the hex string when decoded is http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510:

User-to-User: 687474703a2f2f6469616c6f67666c6f772e676f6f676c65617069732e636f6d2f763262657461312f70726f6a656374732f6763702d70726f6a6563742d69642d31323334352f636f6e766572736174696f6e732f4349442d3239373336333732335f37393133313735395f373939373833353130;encoding=hex;purpose=Goog-ContactCenter-Conversation

Additional data can be sent using separate UUI headers having different "purpose" values. These values are added to the Conversation.telephonyConnectionInfo object. Note that this data is not available to the Conversational Agents (Dialogflow CX) agent at runtime.

Pass in human-agent information

If you need to pass information specific to human agents, you can set the Session Description Protocol (SDP) media label attribute, for the human-agent, Real-time Transport Protocol (RTP) stream to the required data value. Example: none a=label:7382373482 This data will be populated in the sip_recording_media_label field and available in the New message notification pubsub topic containing the transcripts. Look for the sip_recording_media_label field in the pubsub Message.attributes message.

Warning: For compliance reasons, don't pass any PII user data in SIP headers. They should be used to pass non-PII key and value pairs only.

Configure participant roles and media stream order

By default, the first media stream is associated with the END_USER participant role and subsequent media streams are associated with the HUMAN_AGENT participant role.

If you require different behavior (for example, in an outbound calling system), then the URL passed in the header should have the roles parameter appended.

Example: none http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510?roles=HUMAN_AGENT,END_USER

The URL specifies that the first media stream should have the HUMAN_AGENT role and the second media stream should have the END_USER role. You can apply the roles parameter with the Call-Info or UUI SIP header.

Set additional parameters on a given conversation

To set additional parameters on a given conversation, use the MatchIntentRequest RPC call. You can set query_params.parameters to the required key value pairs and query_input.text to something like 'Setting parameters'.

Make the API call after the 200 OK response for the initial SIP INVITE, at which point the conversation has been created. The session ID for the MatchIntentRequest is the same conversation ID provided in the Call-Info header in the INVITE.

Use SIP REFER to transfer a call to a SIP endpoint

To transfer a call from a virtual agent to a SIP endpoint, use the SIP REFER method. Include a payload in the Live agent handoff field and set the Telephony transfer call field to the number that's set in the outbound SIP REFER Refer-To field. Your payload should look similar to the following code sample.

{
    "sip-refer": true
}

Troubleshooting

The Google team might ask you to provide the following artifacts to aid in troubleshooting of the SIP OPTIONS ping and the test calls conducted:

1. Network packet capture
2. SIP debug trace showing full header and SIP SDP:
   • Call-ID value
   • Call-Info value (if exist)

Network packet capture

The network packet capture should show the following:

1. A complete 3-way TCP handshake (SYN, SYN-ACK, ACK) between the your SBC to GTP SIP servers communicated over TCP port 5672. If TCP connection failed to be established, possible issues are:

   • Your network is blocking outbound traffic.
   • Communication is not being sent to one of the regionalized GTP SIP server. See Telephony connectivity network requirement.
   • Communication is not being sent over TCP port 5672.

2. A complete TLS connection handshake with the following:

   • TLS v1.2 or later initiated by your SBC.
   • Your SBC initiating a "Client Hello" and GTP responding with "Server Hello".
   • Mutual TLS authentication process.
     • GTP responds with its own server TLS certificate which is authenticated by your SBC.
     • The SBC sends its own client TLS certificate which is authenticated by GTP.
   • Encrypted channel established as evident by "Encrypted Handshake Message".
   • Evidence of "Application Data" being transmitted over TLS channel.

   If TLS connection failed to be established, possible issues are:

   • SIP trunk has not been created on the GTP side.
   • The SIP trunk configured FQDN does not match the FQDN presented in the TLS certificate (CN or SAN attribute) from the SBC.
   • TLS version not supported, only TLS version 1.2 or later are supported.
   • Requested cipher suite not supported, see SBC's TLS Configuration.
   • Untrusted TLS certificate providers, see SBC's TLS Configuration.

3. The SIP debug trace should show the following:

   • Customer Call-Info SIP header inserted in this format: none Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/$PROJECT_ID/conversations/$CONVERSATION_ID>;purpose=Goog-ContactCenter-Conversation

     Example: none Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510>;purpose=Goog-ContactCenter-Conversation

   • SIP headers show the phone number in E.164 format ([phone]).

   • SIP headers show public IP addresses being used in the request URI and other SIP header fields (for example To, From, Via). Private IP addresses would be rejected.

   • SIP SDP connection information (c= ... ) is specified with a public IP address. Private IP addresses would be rejected.

   • Ensure the media prioritization sends the end users stream first followed by the human agent's media stream second because GTP treats the first media stream as the end users by default.

   If you receive a SIP error response code:

   • SIP 400's error (for example, 488 Not Acceptable Here) response code likely indicates that GTP rejected a SIP header or SIP media SDP configuration.
   • A SIP 600's error (SIP 603 Declined Error) response code likely indicates a quota-related issue. See the Quotas & limits page for details about how to request an increase.

Trigger an action when the remote caller hangs up

Note: This feature is only supported in Playbook Live agents.

The new BiDi API (use_bidi_streaming=True in the ConversationProfile) supports triggering a tool call within a playbook or a webhook call within a flow when the remote caller hangs up.

When the remote caller hangs up and Conversational Agents (Dialogflow CX) receives a SIP BYE message, the custom event sys.remote-call-disconnected is triggered. If you create a handler with this specific event name, you can then use it to trigger a tool call with a playbook or a webhook call within a flow.