CTI Integration with SAP Sales Cloud V2: A Technical Guide

A customer calls. Before your colleague says hello, the caller’s name, company and open topics should already be on screen, and when the call ends, it should be logged in the CRM without anyone typing it in. That is CTI (computer telephony integration). The concept is simple; the implementation has more moving parts than most people expect.

SAP Sales Cloud V2 and Service Cloud V2 share an Agent Desktop that can host a CTI widget from a third-party provider. SAP documents that framework in the guide SAP Service Cloud Version 2 integration with Third-Party CTI Providers. What SAP does not supply is the connection to your telephony system: that layer you build or buy. We have done both, and our product Engage CTI is the result. This guide describes the architecture and the places where projects tend to go wrong.

TL;DR: A CTI integration with SAP Sales Cloud V2 has four parts: the telephony system, middleware (in our case on SAP BTP), the V2 APIs for caller lookup and call logging, and a widget in the Agent Desktop that talks to the shell through XML payloads. The decisions that matter most: push events over WebSocket instead of polling, normalise phone numbers to E.164 on both sides, keep a lookup cache so the screen pop arrives within about two seconds, and handle recording consent according to Swiss law.

What is CTI and why does it matter for Sales Cloud V2?

Without CTI, every call starts with a search: who is this, which account, is there an open case? After the call, someone has to create the phone activity by hand, and often nobody does. CTI removes both steps. The caller is identified before the call is answered, and the activity is logged automatically.

A CTI integration with SAP Sales Cloud V2 has four components.

Telephony system. Your PBX or cloud telephony, for example Microsoft Teams Phone, a browser-based softphone such as Twilio Voice, or a SIP-based PBX. This is where calls actually happen.

CTI middleware. A server-side component that bridges telephony and CRM. It translates telephony events (incoming call, connected, ended) into CRM actions (screen pop, create activity). In our architecture it runs on SAP BTP.

Sales Cloud V2 APIs. The REST APIs used to find contacts, individual customers and accounts by phone number, to read account context and to create phone call activities.

Agent Desktop widget. A UI component inside the Agent Desktop with call controls (answer, hold, transfer, end) and caller information. It runs in a frame and talks to the shell through the browser’s postMessage API.

How does an inbound call flow through the system?

The target for the whole flow, from ring to caller context on screen, is under two seconds. Slower than that and users stop trusting it.

1. The call arrives at the telephony system. It sends a call event to the middleware via webhook or WebSocket.
2. The middleware looks up the caller’s number in Sales Cloud V2. Engage CTI searches in three tiers, first match wins: contacts, then individual customers, then accounts.
3. The middleware pushes the caller context (name, account, open cases, recent interactions) to the widget over WebSocket.
4. The widget notifies the Agent Desktop shell, which shows the screen pop and opens the matching record.
5. When the call ends, the middleware creates a phone call activity in V2 with direction, duration, participants and notes.

The two-second target is not arbitrary. It is roughly the moment a colleague would otherwise ask “who’s calling?”. A screen pop that arrives after that point gets ignored.

The Agent Desktop side of step 4 has rules that are not obvious from the public guide: the shell parses XML only, maps only the actions NOTIFY and END, and recognises a session solely by its reference ID. We documented them in native screen pop in the SSCV2 Agent Desktop.

What are the key technical decisions?

Should you use WebSocket or polling?

The widget needs call events in real time. Polling the middleware every second creates load and still adds latency. A WebSocket connection delivers events as they happen.

We run a WebSocket server on BTP (Node.js) that keeps a connection with each active Agent Desktop session. When a call event arrives from the telephony system, it is pushed to the right user’s connection immediately.

Why not Server-Sent Events? They work for one-way streaming, but CTI is two-way: the widget sends commands back (hold, transfer, end call). WebSocket handles both directions on one connection.

How do you handle phone number matching?

This sounds simple and is not. The same number arrives as +41 44 123 45 67, 044 123 45 67 or 0041441234567. The middleware has to normalise before it searches.

We normalise to the international E.164 format (+41441234567). Sales Cloud V2 stores phone numbers as users entered them, so the formats in the CRM are inconsistent. Normalise both sides: the incoming number and the stored numbers you compare against. If you skip the stored side, you get matches that fail for no visible reason, and your support team will spend a long time looking for them.

Keep a lookup index. Searching the V2 API with wildcard phone queries on every call is too slow for a two-second budget. Our middleware keeps a lookup table that maps normalised numbers to V2 records and refreshes it when records change.

How does authentication work?

The widget runs inside the user’s Agent Desktop session; the middleware calls the Sales Cloud V2 APIs on the user’s behalf. We use SAP’s identity services on BTP (the AppRouter with XSUAA) and the customer’s identity provider, so users do not log in a second time.

Authentication between telephony and middleware depends on the provider: API keys for some, OAuth for cloud services such as Microsoft Teams. The middleware hides this behind one adapter interface, so connecting another telephony system means writing one adapter. The V2 side stays the same.

What gets logged when a call ends?

Every call creates a phone call activity in Sales Cloud V2. We log:

• Direction: inbound, outbound, missed
• Duration: start time, end time, talk time
• Participants: caller, called party, any transferred parties
• Account context: which account or contact was matched
• Notes: entered by the user during or after the call in the widget
• Recording link: if the telephony system records calls, we store the link, not the file

The activity carries the same reference ID that the widget used for the session in the Agent Desktop. That one ID has to be identical in every message for the call; if two components generate their own, the visible part works and the cleanup does not.

Which telephony systems can you connect?

Engage CTI supports these setups today:

Telephony	How it connects	Notes
Microsoft Teams Phone	Teams integration	Most common setup: users keep their Teams number and client; hold, transfer and pickup run from the widget
Browser calling (Twilio Voice)	Twilio Voice SDK	Calls in the browser inside the Agent Desktop, headset instead of desk phone
SIP-based PBX	Provider adapter	Existing PBX connects through an adapter; the SSCV2 side stays the same

Other systems, for example contact centre platforms with their own event APIs, connect through the same adapter pattern. The effort depends mainly on how well the provider’s event model is documented, which is why we look at the provider’s API before we estimate.

What are the most common CTI pitfalls?

Latency. If the screen pop appears after the user has already asked who is calling, nobody will use it. Target under two seconds and test with real call volumes, not demo calls.

Phone number data quality. If the CRM holds phone numbers in fifteen formats, matching fails. Clean and normalise the numbers on all accounts and contacts before go-live. Boring work, and not optional.

Unstable WebSocket connections. Corporate proxies, VPNs and network changes interrupt them. Reconnect automatically with exponential backoff and show a clear “disconnected” indicator in the widget, so users know when CTI is not active.

Several browser tabs. Users open multiple tabs, but only one should handle the call. We use leader election over the BroadcastChannel API so the screen pop happens in exactly one tab. Without it, users get duplicate pop-ups or none.

Transfer context. When a call is transferred, the context has to follow, and the second colleague should see the same screen pop. That requires tracking call sessions, not individual call legs.

Recording and compliance. In Switzerland, recording a non-public conversation without the consent of the participants is a criminal offence (Art. 179ter Swiss Criminal Code), with narrow exceptions for certain business calls. Your CTI solution needs configurable recording controls, and your legal team should sign off on the setup.

How do you deploy CTI on SAP BTP?

The middleware belongs next to the CRM, not inside it. On SAP BTP, Cloud Foundry runtime, our architecture consists of:

• A Node.js application that provides the REST API and the WebSocket server
• A database for the phone number lookup table and session state
• The AppRouter with XSUAA for authentication and tenant isolation

The widget is a small web application that loads inside the Agent Desktop frame.

For multi-tenant operation (several customers on one middleware instance), each customer’s telephony events are routed to their own tenant only. Data isolation is not negotiable here. How we build extensions of this kind on BTP in general is described in extending SAP Sales Cloud V2 with custom Cloud Foundry apps on BTP.

Where this runs in practice

At Nussbaum Matzingen, a Swiss packaging manufacturer, Spadoom Engage was one of three custom BTP apps in the Sales Cloud V2 project: incoming calls are recognised and the matching customer record opens immediately. The project, from no CRM to go-live in five months, is described in how Nussbaum got full pipeline visibility with Sales Cloud V2. We also run the same widget in our own CRM.

---

Want to connect your phone system to SAP Sales Cloud V2 or Service Cloud V2? Get in touch. Engage CTI is also available as a packaged product, with pricing and a 10-day trial at spadoom.cloud.

Frequently asked questions

How long does a CTI integration take?

It depends on the telephony system. Engage CTI runs as multi-tenant SaaS on SAP BTP, so with Microsoft Teams Phone or browser calling via Twilio there is nothing to install: we set up your environment and users take calls inside the Agent Desktop. A custom build or a new PBX adapter takes longer, and the effort depends mainly on the provider’s event API, which we review before giving an estimate.

Does CTI work with Sales Cloud V2 on mobile?

The CTI widget is designed for the Agent Desktop in the browser, where users handle calls at their workstation. Mobile users see the phone activities that CTI logged, because those are standard V2 activities. Where field teams need telephony on the phone itself, it can be built into a mobile BTP app, as we did with the integrated telephony in intelligentfood’s field sales apps.

What happens if the CTI middleware goes down?

Calls still work, because the telephony system does not depend on the middleware. Users just do not get screen pops or automatic logging until it is back. On BTP Cloud Foundry the middleware runs with automatic restarts and health checks, and the lookup table is stored in a database, so a restart does not require rebuilding the index.

Can CTI handle high call volumes?

Yes, if the design is right. The Engage CTI middleware on SAP BTP handles more than 500 concurrent WebSocket connections and processes a call event in under 50 ms (Engage CTI). For larger contact centres it scales horizontally on Cloud Foundry, with session affinity so each WebSocket connection stays on its instance.

Is call recording data stored in Sales Cloud V2?

No, and it should not be. Recordings stay in the telephony system’s storage; we store only the link on the phone call activity in V2. That avoids storage costs, keeps sensitive audio in the telephony system’s compliance-managed environment and respects data-residency requirements. Users open the recording through the telephony system’s own player.