Rework & Improve CTI API (#213)

* Maintenance: Re-arrange structure for CTI API (fit it into general API scope) * Maintenance: Rewrite introduction, endpoint and event intro * Closes #159 Closes #109 - Rework CTI-API documentation * Maintenance: Specify how blocking works a bit more * Maintenance: Rework structure (again) to reduce page lengths * Maintenance: Improve code styling * Add: "Next logical steps" * Maintenance: Fix & Improve user attribute errors * Maintenance: Fixed typos, moved content and remove useless content as per Gerrits QA * Maintenance: Fix typo * Maintenance: Improve CTI Limitations As per Martins internal QA * Maintenance: Improve event list back to its "roots" As per Martins internal QA * Maintenance: Add explaining heading as per Gerrits QA * Maintenance: Fix issues as per Martins technical QA * Maintenance: Add condensed feature list * Maintenance: Improve array value notes
zammad · Mar 6, 2022 · 68253fe · 68253fe
1 parent f384f0e
commit 68253fe
Show file tree

Hide file tree

Showing 9 changed files with 768 additions and 202 deletions.
diff --git a/api/generic-cti/answer-event.rst b/api/generic-cti/answer-event.rst
@@ -0,0 +1,208 @@
+Call answered
+=============
+
+.. include:: /api/generic-cti/cti-endpoint-limitations.include.rst
+
+.. list-table:: Available attributes and sample data for answered events
+   :widths: 20, 40, 40
+   :header-rows: 1
+
+   * - Attribute
+     - Possible value
+     - Description
+   * - ``event``
+     - ``answer``
+     - Tell Zammad that someone answered the call.
+   * - ``from``
+     - e.g. ``493055571600``, ``02214710334``, ``anonymous``
+     - Number that initiated the call
+   * - ``to``
+     - e.g. ``49221470334``, ``03023125771``
+     - Number that is being called
+   * - ``direction``
+     - ``in`` or ``out``
+     - The call direction - if your agent initiates a call this will be ``out``
+   * - ``callId``
+     - e.g. ``53ba82e2bd6d12d9fb2d3838f0cfb070``, ``5fb9532f40da834a``,
+       ``123456789``
+     - An ID that is unique for the call. Zammad will use this ID to identify
+       an existing call with following actions
+       (e.g. like answering or hanging up)
+
+       *This ID must be unique per call session*.
+   * - ``answeringNumber``
+     - e.g. ``42``, ``jdoe``, ``jdoe@example.com``, ``49221470351``,
+       ``03023125184``
+     - Zammad will look up for a user with given value, the following
+       attributes will be evaluated in given order:
+
+          * ``user.phone``
+          * ``user.login``
+          * ``user.id``
+
+       This value is optional.
+   * - ``user``
+     - e.g. ``John Doe``, ``[Alice, Bob]``
+     - The user(s) real name involved. You may have to provide array style
+       (``[]``) params depending on the call method you choose.
+
+       | If the direction is ``out``, this is the name of the calling person(s).
+       | If the direction is ``in``, this is the name of the called person(s).
+
+       This value is optional.
+
+There's two options on how to ``POST`` the relevant data to Zammad.
+
+.. include:: /api/generic-cti/generic-cti_context-note-configuration.include.rst
+
+.. tabs::
+
+   .. tab:: JSON (recommended)
+
+      ``POST``-Request sent:
+      ``https://{FQDN-Zammad}/api/v1/cti/{instance specific token}``
+
+      Outbound
+         Payload:
+
+            .. code-block:: json
+
+               {
+                  "event": "answer",
+                  "from": "493023125741",
+                  "to": "492214710334",
+                  "direction": "out",
+                  "callId": "9f1840cb-8be9-4d3a-8200-3da2937085f0",
+                  "caller": "Christopher Miller"
+               }
+
+
+         Response:
+
+            .. code-block:: json
+
+               {}
+
+         Sample curl command:
+
+            .. code-block:: sh
+
+               $ curl --request POST 'https://{FQDN-Zammad}/api/v1/cti/{instance specific token}' \
+                  --header 'Content-Type: application/json' \
+                  --data-raw '{
+                     "event": "answer",
+                     "from": "493023125741",
+                     "to": "492214710334",
+                     "direction": "out",
+                     "callId": "9f1840cb-8be9-4d3a-8200-3da2937085f0",
+                     "caller": "Christopher Miller"
+                  }'
+
+      Inbound
+         Payload:
+
+            .. code-block:: json
+
+               {
+                  "event": "answer",
+                  "from": "493023125741",
+                  "to": "492214710334",
+                  "direction": "in",
+                  "callId": "307fa962-de8d-4ffc-817b-7f6993204159",
+                  "answeringNumber": "emma@chrispresso.com",
+                  "caller": ["Christopher Miller", "Emma Taylor"]
+               }
+
+         Response:
+
+            .. code-block:: json
+
+               {}
+
+         Sample curl command:
+
+            .. code-block:: sh
+
+               $ curl --request POST 'https://{FQDN-Zammad}/api/v1/cti/{instance specific token}' \
+                  --header 'Content-Type: application/json' \
+                  --data-raw '{
+                     "event": "answer",
+                     "from": "493023125741",
+                     "to": "492214710334",
+                     "direction": "in",
+                     "callId": "307fa962-de8d-4ffc-817b-7f6993204159",
+                     "answeringNumber": "emma@chrispresso.com",
+                     "caller": ["Christopher Miller", "Emma Taylor"]
+                  }'
+
+   .. tab:: form-data
+
+      ``POST``-Request sent:
+      ``https://{FQDN-Zammad}/api/v1/cti/{instance specific token}``
+
+      Outbound
+         Payload:
+
+            .. code-block::
+
+               event:"answer"
+               from:"493023125741"
+               to:"492214710334"
+               direction:"out"
+               callId:"371e2cd7-67ff-4fd9-892b-030c8d128fb1"
+               caller[]:"Christopher Miller"
+               caller[]:"Emma Taylor"
+
+         Returns:
+
+            .. code-block:: json
+
+               {}
+
+         Sample curl command:
+
+            .. code-block:: sh
+
+               $ curl --request POST 'https://{FQDN-Zammad}/api/v1/cti/{instance specific token}' \
+                  --form 'event="answer"' \
+                  --form 'from="493023125741"' \
+                  --form 'to="492214710334"' \
+                  --form 'direction="out"' \
+                  --form 'callId="371e2cd7-67ff-4fd9-892b-030c8d128fb1"' \
+                  --form 'caller[]="Christopher Miller"' \
+                  --form 'caller[]="Emma Taylor"'
+
+      Inbound
+         Payload:
+
+            .. code-block::
+
+               event:"answer"
+               from:"493023125741"
+               to:"492214710334"
+               direction:"in"
+               callId:"61868f1e-2171-4313-970b-25982f0c5ce1"
+               answeringNumber:"emma@chrispresso.com"
+               caller="Emma Taylor"
+
+         Returns:
+
+            .. code-block:: json
+
+               {}
+
+         Sample curl command:
+
+            .. code-block:: sh
+
+               $ curl --request POST 'https://{FQDN-Zammad}/api/v1/cti/{instance specific token}' \
+                  --form 'event="answer"' \
+                  --form 'from="493023125741"' \
+                  --form 'to="492214710334"' \
+                  --form 'direction="in"' \
+                  --form 'callId="61868f1e-2171-4313-970b-25982f0c5ce1"' \
+                  --form 'answeringNumber="emma@chrispresso.com"' \
+                  --form 'caller="Emma Taylor"'
+
+The next logical step within call session context would be:
+   * :doc:`hangup <hangup-event>` (call ending)
diff --git a/api/generic-cti/cti-endpoint-limitations.include.rst b/api/generic-cti/cti-endpoint-limitations.include.rst
@@ -0,0 +1,7 @@
+.. warning:: **🚧 Limitations / Notes🚧**
+
+   * Authentication on this endpoint works fundamentally different compared to
+     the rest of the API.
+   * API clients *do not* work with the CTI endpoints unless explicitly stated
+     by the client vendor!
+   * The CTI endpoints are relevant for PBX systems only.
diff --git a/api/generic-cti/generic-cti_context-note-configuration.include.rst b/api/generic-cti/generic-cti_context-note-configuration.include.rst
@@ -0,0 +1,13 @@
+.. note:: **🤔 For your context**
+
+   Below calls have been sent with the following configuration.
+   This is important for *you* to understand the returns we're showing here.
+
+      Outbound
+         * Destination caller ID ``4989*`` set outbound caller ID
+           ``498999998145`` with note "All from munich"
+         * Destination caller ID ``4930*`` set outbound caller ID
+           ``493023125877`` "All from Berlin"
+
+      Other settings
+         * Default caller ID for outbound calls ``496990009111``