DocumentationAPI Reference

Displaying a caller's new ticket in Support

After detecting the system event associated with an agent answering an inbound call, the telephony system can create and display a new ticket in Support to let the agent capture details about the call.

This flow consists of:

  • Making preliminary requests to retrieve the Zendesk user id of both the agent and the caller
  • Making a request to the Talk Partner Edition API to create and display the ticket for that agent in Support

This method also creates a call record in Zendesk which allows the data to be retrieved later, and automatically displays the data in the ticket using the modern Talk Partner Edition voice comment, all with a single endpoint.

  1. Retrieve the agent's Zendesk user id. See Retrieving the Zendesk user id of a call-center agent.

  2. Retrieve the caller's Zendesk user id. You can search for an existing user in Support. See Retrieving the Zendesk user id of a caller.

    If the user doesn't exist in Support yet, create a user profile for the caller. See Creating a user profile in Support for a caller.

  3. Create and display a ticket in Support using the Talk Partner Edition API (not the Tickets API).

    Call the create a call endpoint in the Talk Partner Edition API to create a ticket. This will:

    • Create a new ticket with the subject given by subject

    • Create a call record with the fields passed in the call object and associated it with the ticket

    • Create a voice comment in the ticket whose author’s name and avatar are given by author_id, display the fields given in the call_fields array, and set the title of the comment with the string defined by title

    • Screen-pop the ticket to the agent specified by display_to_agent

{  "call": {    "app_id": 1111,    "end_user_id": 2222,    "agent_id": 3333,    "from_line": "+183808333456",    "to_line": "+149488484873",    "call_started_at": "2022-01-27T15:31:40+01",    "direction": "inbound",    "voicemail": false,    "call_type": "PSTN",    "end_user_location": "Dublin",    "queue_name": "priority_one",    "ivr_destination_group_name": "Billing",    "external_id": "1245HN567"  },  "comment": {    "title": "Call from ",    "call_fields": ["queue_name", "call_ended_at", "transcript"],    "author_id": 4444,    "display_to_agent": 5555  }}

See Creating a call record in Zendesk for more details about using a call object to save data in Zendesk.

Tickets have a via_id parameter that can be set in order to distinguish the channel from which they were created. When using the create a call endpoint to create a ticket with a voice comment, the via_id parameter is automatically populated based on the values in the direction and voicemail fields.

  • If voicemail is "true", then via_id is set to 44, which is the equivalent of channel "CTI Voicemail"
  • If direction is "inbound", then via_id is set to 45, which is the equivalent of channel "CTI Inbound"
  • If direction is "outbound", then via_id is set to 46, which is the equivalent of channel "CTI outbound"

Creating a ticket and displaying it with the legacy voice comment

Alternatively, you can use the legacy Talk Partner Edition endpoint to create and display a ticket. This uses a simpler and more limited version of the voice comment and does not create a call record in Zendesk.

  1. Retrieve the agent's Zendesk user id.

  2. Retrieve the caller's Zendesk user id.

  3. Create and display a ticket in Support using the Talk Partner Edition API (not the Tickets API).

    Use the create tickets endpoint in the Talk Partner Edition API to create and display the ticket:

    POST /api/v2/channels/voice/tickets.json

    The endpoint takes a JSON object that specifies the viewing agent and describes the ticket:

    {  "display_to_agent": 1234,  "ticket": {    "via_id": 44,    "description": "Voicemail from +16617480240",    "subject": "My printer is on fire!",    "voice_comment": {        "from": "+16617480123",        "to": "+16617480123",        "recording_url": "http://yourdomain.com/recordings/1.mp3",        "started_at": "2013-07-11 15:31:44 +0000",        "ended_at": "2013-07-11 15:32:44 +0000",        "call_duration": 40,        "transcription_text": "The transcription of the call",        "location": "Dublin, Ireland"     }    "requester_id": 5678,    "tags": ["premier-status", "call-center"],    "priority": "urgent"  }}

    Note that you must manually specify a value for via_id as either 44 (voicemail), 45 (inbound call), or 46 (outbound call).

You can save more details about the call by adding one or more tags to the ticket, or by using custom ticket fields to record the information. See Saving other data in a ticket.