Hannes
June 7, 2018, 10:27am
1
Hi there,
if you use or intend to use Zammad and the CTI integration, feel free to join the discussion here:
opened 02:37PM - 28 May 18 UTC
closed 12:12PM - 17 Jun 20 UTC
enhancement
verified
# Writeup: Generic CTI integration
# Starting point
In many use cases, agent… s work in connection customer conversations over the phone.
It is a great relief when the telephone system (PBX) is integrated with Zammad, which makes processes with agents more effective.
The goal of the document is to provide the necessary API documentation to enable PBX vendors to easily integrate with Zammad.
# Feature list
## Inbound
* Caller identification based on the CallerID (open a customer profile with just one click)
Display of open and closed tickets of a customer in a special overview. This overview should also give the possibility to create a ticket for the given customer.
* Intelligent mapping of CallerIDs with direct (e.g. directly at the contact) and not direct (e.g. telephone numbers from the signature)
* Caller Journal (which calls have been made and which have been handled and which require a callback)
* Blocking of CallerIDs (already during the call) *
* Support to allow an agent to set a DND - like state *
* Overview of agents who currently handle a call
## Outbound
* Direct dialling of the customer telephone number *
* Set the outbound caller ID based on the line phone number (e. g. set sender caller id based on country of destination caller id) *
_* if supported by the PBX/telephone system_
# CTI Push API
## How it works
Events can be transferred in realtime from the telephone system to the Zammad CTI Push API (REST API) via a generic interface.
Depending on the event, Zammad offers various functions to quickly and easily identify callers and the corresponding tickets, for example, or to provide a caller log. Or to modify the incoming or outgoing call.
## Endpoint
The endpoint of your Zammad CTI Push API looks like http://localhost:3000/api/v1/integration/cti/:token and can be found in Zammad -> Admin -> Integrations -> CTI (generic) -> Endpoint
## Events
Zammad supports the following three events (newCall, hangup and answer) in version 2.x.
### Event: newCall
Attribute | Description
-- | --
event | "newCall"
from | The calling number (e.g. "493055571600" or "anonymous")
to | The called number (e.g. "491711234567890")
direction | The direction of the call (either "in" or "out")
callId | A unique alphanumeric identifier to match events to specific calls (max. 250 characters)
user[] | The user(s) realname involved. It is the name of the calling user when direction is "out", or of the users receiving the call when direction is "in". Group calls may be received by multiple users. In that case a "user[]" parameter is set for each of these users. It is always "user[]" (not "user"), even if only one user is involved.
You can simulate this POST request and test your server with a CURL command:
```
curl -X POST --data "event=newCall&from=493055571600&to=491711234567890&direction=in&callId=123456&user[]=Alice&user[]=Bob" http://localhost:3000/api/v1/integration/cti/:token
```
#### The response (optional)
After sending the POST request to Zammad, your PBX can accept an JSON response to determine what to do (e. g. for `direction=in` to block the caller or for `direction=out` to set a caller id).
Zammad currently supports the following responses for incoming calls:
Action | Description
-- | --
reject | Reject call or pretend to be busy (depending on your settings in Zammad)
Example 1: Reject call signaling busy
```
{
"action": "reject",
"reason": "busy"
}
```
Zammad currently supports the following responses for outgoing calls:
Action | Description
-- | --
dial | To set the caller id (depending on your settings in Zammad). Number need to be in E.164 format.
Example 1: Set custom caller id for outgoing call
```
{
"action": "dial",
"callerId": "493055571642",
"number": "491711234567890"
}
```
### Event: hangup
Attribute | Description
-- | --
event | "hangup"
callId | Same as in newCall-event for a specific call
cause | The cause for the hangup event (see below)
from | The calling number (e.g. "493055571600" or "anonymous")
to | The called number (e.g. "491711234567890")
direction | The direction of the call (either "in" or "out")
answeringNumber | The number which was answering
You can simulate this POST request and test your server with a CURL command:
```
curl -X POST --data "event=hangup&cause=normalClearing&callId=123456&from=493055571600&to=491711234567890&direction=in&answeringNumber=4921199999999" http://localhost:3000/api/v1/integration/cti/:token
```
Hangup causes: For these reasons, hangups may occur because of these causes:
Attribute | Description
-- | --
normalClearing | One of the parties hung up after the call was established.
busy | The called party was busy
cancel | The caller hung up before the called party picked up
noAnswer | The called party rejected the call (e.g. through a DND setting)
congestion | The called party could not be reached
notFound | The called number does not exist or called party is offline
forwarded | The call was forwarded to a different party
### Event: answer
Attribute | Description
-- | --
event | "answer"
callId | Same as in newCall-event for a specific call
user | Name of the user who answered this call. Only incoming calls can have this parameter
from | The calling number (e.g. "492111234567" or "anonymous")
to | The called number (e.g. "491711234567890")
direction | The direction of the call (either "in" or "out")
answeringNumber | The number of the answering destination. Useful when redirecting to multiple destinations
You can simulate this POST request and test your server with a CURL command:
```
curl -X POST --data "event=answer&callId=123456&user=John+Doe&from=493055571600&to=491711234567890&direction=in&answeringNumber=21199999999" http://localhost:3000/api/v1/integration/cti/:token
```
## Credits
Thanks to the people at [sipgate](https://www.sipgate.io/) for inspiring ❤️.
We like to here your feedback.
Thank you!
Johannes
lr1980
June 7, 2018, 11:37am
2
we installed 2.5 and cannot find a CTI config section?
Newan
June 7, 2018, 11:40am
3
section is called sipgate, you can used it with all PBX system that call the events
lr1980
June 7, 2018, 11:42am
4
ok… but the GitHub issue says
The endpoint of your Zammad CTI Push API looks like http://localhost:3000/api/v1/integration/cti/:token and can be found in Zammad → Admin → Integrations → CTI (generic) → Endpoint
so we searched that
I tried the docker images and there is a CTI integration setting entry. We upgraded zammad from rpm repo. Do we need some more config / setting after we upgrade with rpm package from 2.4 to 2.5 to see the CTI integration???
You found “CTI (generic)”?
At the zammad.com (2.5) branch is no “CTI (generic)” entry
I’m confussed at the moment ^^
I cannot find this entry in my 2.5 rpm based install, too.
lr1980
June 12, 2018, 4:07pm
8
I think I found the problem => in “/opt/zammad/app/assets/javascripts/app/controllers/_integration/” the file “cti.coffee” is missing on our installation. So I looked into the log at https://packager.io/gh/zammad/zammad/builds/3144/logs/centos-7 and found:
BUNDLED WITH
rm app/assets/javascripts/app/controllers/layout_ref.coffee
rm -rf app/assets/javascripts/app/views/layout_ref/
rm app/assets/javascripts/app/controllers/karma.coffee
rm app/assets/javascripts/app/controllers/_integration/cti.coffee
I don’t know why there is a “rm”…
I added this file manually and run
zammad run rake assets:precompile
and now I can see the config entry…
2 Likes
Hi, yes it’s scheduled for Zammad 2.6 and not available in RPM.
To enable it in Zammad 2.5 (stable) the way from @lr1980 is correct. Thanks @lr1980
I quickly hacked a Perl script together that can push our queue calls from Asterisk to Zammad’s CTI interface; the results look promising. I have the following two suggestions though:
Our Asterisk uses a AGI script that queries our CRM to map CALLERID(num) to a proper CALLERID(name):
If I call from my mobile phone number +49 176 xxxxx, it sets the name to “von Wittich, Martin (IServ GmbH)”.
If a German landline number calls, it will additionally postfix the name with “[City]”, e.g. the name for +49 531 xxxxxxx will be postfixed “[Braunschweig]”. This means that even numbers that can’t be resolved in our CRM will have some meaningful information for our agents.
It would be nice if Zammad would support an additional field displayName (or something like that) in the newCall event so I could hand this information over to Zammad. It would probably only be useful in the phone overview and not for creating customers, but it should greatly help agents identify calls when Zammad doesn’t know the customer yet.
Maybe even additional fields like firstname, lastname, email, … might be useful? Then Zammad could receive the necessary information for creating new customers directly from the CTI interface, provided that the PBX can supply it of course.
Creating tickets from phone calls seems to be needlessly complicated: I have to click on the caller, then on small action button on the top right, and then on “New Ticket”. That’s IMO pretty hidden. I think a “Create Ticket” button directly in the phone overview would improve it.
martini
December 21, 2018, 7:30am
11
Hi @martin.von.wittich
a new topic for this issue would be nice. I’ll rely on it asap.
Greetings,
-Martin
Hannes
July 29, 2019, 2:27am
13
This topic was automatically closed after 416 days. New replies are no longer allowed.
The CTI integration was introduced with Zammad 2.6.Release | Zammad 2.6.0 & 2.5.1 (Major and Patch Level)
