Guidelines for CTI Integrations with Zendesk

We recommend following the guidelines outlined in this article when building a telephony app using the Zendesk Apps framework. These guidelines serve multiple purposes:

• They assist in maintaining your Zendesk account's performance and ensuring a seamless experience for agents.
• They facilitate a quicker and smoother transition when migrating between framework versions.
• They can help prevent disruptive changes and increase the likelihood of your app being approved for public use after its initial submission.

If you aren't sure about any of the points below, have questions about the approval process, or if you're seeking guidance or assistance, feel free to get in touch at [email protected].

Call console

• Call console size. The call console (or call widget) is where agents spend most of their time while taking calls in Zendesk. The following table outlines recommended sizes for best visibility and ease of use.

  	Minimum (pixels)	Maximum (pixels)
  Width	250	320
  Height	405	520

• Agent state selector visibility. Throughout the day agents will switch their state to make themselves available to take calls or stop receiving them (even more often if your app has not yet implemented Zendesk's Agent State APIs). The call console should have the agent state selector clearly visible at all times.

• Configuration options. The following are common configuration option locations:

  • Placing configuration options on the call console
  • Placing configuration options under Zendesk "Apps & Integrations" section
  • Placing configuration options on an external admin page

  The best strategy depends on your specific requirements and the users who are expected to modify these options. For example, if your app provides an option to alter the ringtone, it would be more convenient to locate this within the call console, as it can be quickly accessed by the agent and only impacts that specific app instance. If, however, your integration offers a configuration to generate a ticket for each abandoned call, this should be located outside the call console and limited to admin or supervisors only. It's important to logically position settings and avoid scattering them across numerous locations. This prevents confusion for users trying to remember where to go to adjust a particular setting.

• Screen-popping tickets and users outside the call console. Talk Partner Edition offers endpoints that enable tickets and users to be screen-popped in the agent's browser. These endpoints provide quick access to calls, tickets, and users displayed in the call console. For example, if your app displays a call history along with their numbers, there should be a link to open these customers' profiles and the calls (or the tickets linked to them) in Zendesk. When a call is received, your app should search for existing tickets and users in Zendesk, and either immediately screen-pop them or provide an option for the agent to do so. See Call Flow.

• Tags and notes. Tags, notes, and call recordings gathered in the call console should be moved to the corresponding ticket post-call. Agents prefer having all pertinent information consolidated in one location — the ticket. Storing this data in Zendesk enables additional functionalities for customers, like the use of triggers and business rules. Any other information that is related to the case, but not directly to the call, should be stored in Zendesk as custom ticket fields. For more information, see Custom Ticket Fields.

• Keypad main focus Avoid making the keypad the central element (or the "home screen") of your UI, or even worse, the sole method for entering numbers and extensions. Text input fields are more efficient.

Saving call data

Talk Partner Edition provides partners with a Call Object, a storage mechanism with endpoints for creating, updating, and retrieving call data. A comprehensive list of fields that can be stored in this object can be found in the Calls endpoint. Once the data is stored in the call object it can be used in other parts of Zendesk to offer additional functionalities to customers, such as native reporting on Explore.

When inputting data into the call object, Zendesk primarily validates the format of the fields — dates should be in date format, numbers should be numerical, and so forth. For entity IDs, such as Ticket, Organization, and Users, we validate if they exist in the customer account. However, our joint customers expect the data to adhere to certain industry standards; more importantly, if they are transitioning to your app from another partner, they expect to interpret the data in the same manner. It's likely that you provide your own reporting tools, and it would be frustrating for our customers if they generated different metrics from the same attributes in different locations.

When storing data related to call times we strongly recommend sticking to the following rules:

• time_to_answer should be equivalent to ivr_time + queue_time.
• wait_time should be equivalent to the duration of the greeting + time_to_answer.
• duration should be measured from the moment the caller hears the greeting until the agent hangs up.
• consultation_time is a part of `hold_time``.
• talk_time should be measured from the moment the agent answers the call until they hang up (when the wrap-up time commences), and should not include hold_time or consultation_time.

Custom ticket fields

Until recently, one of the primary methods to store call data in Zendesk was through the use of custom ticket fields. Developers would utilize these fields to store transactional call data, such as call duration and wait time, primarily to make this information accessible in Explore for reporting purposes.

However, merging ticket information with call data often led to complications. For instance, if a ticket involved multiple calls and the partner updated the ticket with data from the latest call, it would overwrite any information from previous calls.

With Talk Partner Edition, call data is now independent. A call doesn't necessarily have to be linked to a ticket, and a ticket can have multiple associated calls.

• Data storage in custom fields: Avoid using custom ticket fields to store data that can be stored in the call object. All fields in the standard call object are now considered call data, not ticket data.
• Call data storage: Custom ticket fields can still be used to store information gathered during calls, provided that the information is specific to the case and not the call. Examples include order details, serial numbers, and billing and shipping information.
• Custom fields for workflows: Fields from the call object cannot be used directly by triggers and business rules in the same way that custom ticket fields can. If you want to offer this capability, you may still need to use custom ticket fields. Note, however, that all fields from the call object displayed in the ticket via the new TPE voice comment are indexed and searchable like any other comments, and thus can be used to trigger actions based on their text content.
  • If your integration does employ custom ticket fields, group them in a custom form and switch to this form when updating the ticket.

Displaying call data in the ticket

There are two ways of displaying data from calls in the ticket

• Voice comments
• Internal comments

Voice comments

In Talk Partner Edition, voice comments have been enhanced and offer greater flexibility. They can display almost any field stored in the call object in a consistent manner. Regardless of the integration used, agents will always find the call data in the same location, formatted uniformly.

The Talk Partner Edition voice comment presents the most relevant information while still allowing the agent to delve deeper if necessary. They can display a wealth of data without significantly increasing the space taken up in the ticket.

• Marking interactions with voice comments: Utilize voice comments to denote user interactions. Consider posting voice comments at the start and end of the call to indicate the beginning and conclusion of the user interaction.

  Because the voice comment by default always appears closed and features a row of icons at the top to represent common data such as direction and location, you can post concise one-line voice comments that convey a lot of information despite their brevity. Additionally, you should customize the title parameter in the comment to clarify its content and the part of the interaction it refers to. For example: "call started", "transferred call finished", "voicemail call summary", "overflowed call", and so forth.

• Display the comment author. A Zendesk ticket can contain interactions from several channels. For instance, the conversation can start with an inbound call (which creates the ticket) and later continue via SMS or messaging. To provide a more conversational tone, we strongly recommend that the author of the comment (given by the author_id parameter) displayed at the top of the comment corresponds to the user that initiated that particular interaction.

• Use voice comments to display helpful information. Use the initial voice comment to display any information that assists the agent in answering the caller. Information such as wait_time, ivr_action, ivr_routed_to, and ivr_destination_group_name helps the agent to address the caller properly and prevent them from asking questions that the caller would (reasonably) assume they should know already.

• Don't include metadata in title. Avoid including metadata in the title of the comment such as "call with unknown caller [phone]". This type of information is better displayed in the comment itself where it is properly formatted.

• Tailor the voice comment to the user case. Adjust the content of the voice comment according to the use case instead of including the entire call object. For example, if a voice comment was created from a callback it should include the callback-related fields such as callback_number. If the call was forwarded to a configured overflow number, it should display the overflow_to field, and so on.

• Rule of parsimony. Just because your app can display a lot of call object information, it doesn't mean you should display all of it. Consider the context in which the information will be relevant to agents. Many fields are only necessary when they contain non-default values, such as the outside_of_business_hours flag or recording_consent. Remember that all the fields in the call object are also available on Explore, where the customer can create their own reports or export the data.

Managing call recordings

A key feature of a third-party telephony solution is the ability to play back call recordings directly within the ticket without having to open additional windows or leave the workspace.

To display a call recording on a ticket, store the recording's URL in the TPE call object using the recording_URL field. Then pass this field when creating a voice comment. If the agent can access the URL, an embedded player will appear, allowing them to listen to the recording.

Not all telephony systems can expose a URL linked to their externally secured audio file. In these cases, you can use the Attachment API. This API uploads a file, with a maximum size of 50 MB, to Zendesk and returns a local URL. You can store this URL in the call object and display it in the voice comment, eliminating the need for external authentication. With appropriate compression, a 50 MB capacity should be enough for recordings of more than one hour.

Be sure to include the call_recording_consent property to the voice comment if the caller didn't give their consent. This helps the agent to identify cases where the audio player is intentionally not displayed from cases where the recording exists but is misplaced, inaccessible, or has been deleted.

Managing transcripts

We recommend using TPE voice comments for call transcriptions over internal comments, as voice comments can easily collapse and take minimal space in the ticket. Transcriptions that record the speaker and the events in order are desirable due to their clarity. Use line breaks (\n) while storing the text in the transcript field within the call object for improved readability. Example:

Internal Comments

While TPE voice comments are powerful and flexible, they can only display data present in the call object. Until Zendesk provides the capability to expand the standard call object, you'll need to use internal comments to display non-standard call data.

• Avoid the overuse of formatting. If possible, avoid using HTML formatting in comments, such as large fonts and font styles. This can be distracting and result in inconsistent styles in the ticket UI.

• Avoid multiple lengthy comments. Avoid creating too many comments for the same call. Due to headers, margins, and padding, each comment can take a lot of space and hide the actual call information.

• Don't expose low-level information unnecessarily. Avoid revealing internal or technical information in the ticket, such as session ids, object ids, etc. The voice comment automatically displays Zendesk's call_id and your own external_call_id in the footnote of the comment which should suffice for troubleshooting.

Call flow

Below are some good practices when comes to creating tickets and comments during the call flow.

• Ticket creation. Tickets can be generated at any stage during the call flow; creating them earlier (prior to connecting the user to the agent) can be helpful for some customers as it allows them to activate their triggers in Zendesk. This is particularly useful if your system can gather information from the customer during the IVR through data dipping. For example, following your IVR requesting the caller's subscription number, you can immediately create a ticket with that information stored in a custom ticket field, which would then be detected by a trigger in Zendesk activating a webhook that calls back your API.

• Closing voice comment. Consider generating a closing voice comment (the one concluding the interaction with the user) only when recordings and transcripts are available (if your app supports call transcripts). Be aware that if this process takes too long, the agent might close the ticket and you won't be able to add new comments to closed tickets.

• Setting the via_id parameter. When creating tickets in Zendesk using the public Tickets API make sure to set the via_id parameter of the ticket creation public API to either "44", "45", or "46", representing "CTI Incoming call", "CTI Outcoming call", and "CTI Voicemail", respectively. This allows customers to filter tickets created by your integration and to create triggers based on the channel. The via field is set automatically when using the Talk Partner Edition Create Ticket with voice comment API.

• Transferring calls. If the call is transferred to another agent and a ticket was already created for that call, the ticket should accompany the call and be displayed to the agent who received the call.

• Abandoned calls. Most customers want to track the number of abandoned calls they have, but few want to create a ticket for each one. With the old Talk Partner Edition, the only way to know about calls abandoned on a third-party app was to add them to tickets because calls couldn't exist outside of a ticket. With the current Talk Partner Edition, this is no longer necessary; calls exist independently, without associations with tickets or other entities. Your app should offer the customer the option to customize this behavior.