How to Integrate Birdie + Zendesk

This integration is dedicated to importing Support Tickets from your Zendesk account into Birdie. Below are key details about what we need to set up the integration and how tickets and data are imported.

Birdie supports two primary authentication methods for accessing the API: API Tokens and OAuth Tokens. Additionally, if the identification of agents and customers is necessary, it's possible for us to request additional access to the sunshine conversation API.

API Tokens are tied to a specific user account and are used with Basic Authentication. They are long-lasting and remain active until manually revoked. API Tokens inherit the permissions of the associated user account, making them ideal for simpler integrations where access controls and granular permissions are less critical.

To authenticate with the Zendesk API and import data with this method, you'll need to generate an API token that, along with your Zendesk email, can be used to authenticate API requests. You'll need to provide Birdie Team the following information:

• Domain of your Zendesk account (ex.: domain.zendesk.com)
• Valid email with admin access to Zendesk (this will only work for API requests)
• API Token

OAuth Tokens provide a higher level of flexibility, allowing you to set specific scopes and permissions during token creation. OAuth Tokens can have a fixed lifespan or be configured to last indefinitely.

To authenticate with the Zendesk API and import data with this method, you'll need to generate an OAuth token that can be used to authenticate API requests. You'll need to provide Birdie Team the following information:

• Domain of your Zendesk account (ex.: domain.zendesk.com)
• OAuth Token

Steps

1. In Admin Center, click Apps and integrations in the sidebar, then select APIs > API Configuration.
2. In the Settings tab, enable token access.

Steps

1. In Admin Center, click on Apps and integrations in the sidebar, then select APIs > API tokens.
2. Click the Add API token button in the top-right corner.
3. Enter a description for your API.
4. After clicking Save, the token will be displayed only once, so make sure to copy it and store it securely
5. Click Save again to go back to the Zendesk API page.
6. If you click on the token again, only a truncated version will be displayed.
   
7. Share the token securely with the Birdie team

Steps

1. In Admin Center, click on Apps and integrations in the sidebar, then select APIs > Zendesk API.
2. In list of active tokens, find and select the token you wish to delete.
3. Click the Delete button located on the right side of the screen.

Ensure you have administrator access to the Zendesk account used to manage OAuth tokens.

Replace {domain}, {user_email} and {user_password} with your Zendesk account information. Customize the name and identifier fields as you wish.

The response should look like this:

 Note: Save the client_id from this response securely, as they will be required in the next step.

Replace {domain}, {user_email}, and {user_password} with your information and client_id with the identifier obtained when creating the client.

The response should look like this:

Save the full_token securely; this will be used to authenticate API requests.

Share it with the Birdie team using a secure way. 

For Birdie to use this API, it is necessary to provide or create the credentials within the Zendesk account, which requires account administrator privileges.

Steps:

1. In Admin Center, click on Apps and integrations in the sidebar, then select APIs > Conversations API.
2. Click the Create API key button in the top-right corner.
3. Enter a name for your API key and click Next.
4. The App ID, Key ID, and Secret Key will be displayed. The Secret Key is shown only once, so make sure to copy it and store it securely.
5. Click Next again to go back to the Zendesk API page.
6. If you click to view the credendials again, the secret key will be displayed in a truncated version.

Note: If your team needs to include private or internal tickets in Birdie, this behavior can be configured to meet your needs. Contact us to modify the import settings accordingly.

• Groups captures team or department details associated with each ticket groups (see Zendesk's Groups documentation for more details).
• Users (see Zendesk's Users documentation for more details):
  • Agent: Include agent identifiers, roles, or other relevant agent-specific data.
  • Author: Bring in detailed info about the ticket requester (e.g., name, contact details).
• Organization captures company-specific fields, allowing tickets to be linked to specific organizations (see Zendesk's Organizations documentation).

Note: These imports are disabled by default but can be enabled based on your needs.

If your Zendesk setup includes custom fields for tickets, these fields can be mapped directly into Birdie, preserving your unique data structure. Zendesk allows you to store additional, flexible data within tickets beyond standard fields, accommodating various data types. You can define or modify these fields in Zendesk by visiting Zendesk’s Ticket Fields documentation.

Once imported, Zendesk custom fields appear as Birdie custom fields, maintaining consistency across both platforms. Mapped to Birdie’s data structure, these fields enhance data organization and filtering, supporting extended segmentation within Birdie’s interface. This allows for customized workflows and data displays based on the unique attributes of each ticket.