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.

Requirements

Birdie supports two primary authentication methods for accessing the API: API Tokens and OAuth Tokens.

API Tokens

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

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

Managing API tokens

Enabling API token access

API token access is disabled by default. To enable it, navigate to the Admin Center and go to the API settings. Make sure to enable API token access before users can start using API tokens for authentication.

Steps

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

Generating API tokens

To generate an API token, you must be an administrator and have API token access enabled in your account.

Steps

In Admin Center, click Apps and integrations in the sidebar, then select APIs > Zendesk API.
Click the Add API token button next to Active API tokens.
The token will be generated and displayed on the screen.
(Optional) Enter a description for your API token.
Copy the token and store it in a secure location. Once you click Save to close this window, the full token will not be displayed again.
Click Save to go back to the Zendesk API page.
If you click on the token again, only a truncated version will be displayed.

Deleting an API token

Since an API token functions like a password, any verified user on the account or anyone with the email address associated with the account can use it to authenticate API requests. If you suspect that an API token has been compromised, delete it immediately. Deleting a token will deactivate it permanently.

Steps

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

Managing OAuth tokens

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

Create OAuth Client

Use your preferred method (e.g., curl or Postman) to make a POST request to create the OAuth client:

curl https://{domain}.zendesk.com/api/v2/oauth/clients.json -X POST -u {user_email}/{user_password} -H "Content-Type: application/json"  -d '
{
    "client": {      
        "name": "Test Client",      
        "identifier": "test_client",     
        "kind": "confidential"    
    }  
}'

Note: 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:

{
  "client": {
    "url": "https://{domain}.zendesk.com/api/v2/oauth/clients/{client_id}.json",
    "id": {client_id},
    "user_id": {user_id},
    "name": "Test Client",
    "identifier": "test_client",
    "company": null,
    "description": null,
    "redirect_uri": [],
    "secret": {secret},
    "created_at": "2006-01-02T15:04:05Z",
    "updated_at": "2006-01-02T15:04:05Z",
    "global": false,
    "logo_url": null,
    "kind": "confidential"
  }
}

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

Generate OAuth Token

Use the client_id from the previous step to request an OAuth token by making a POST request:

curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens.json -X POST -u {user_email}/{user_password} -H "Content-Type: application/json" -d '
{    
    "token": {      
        "client_id": {client_id},      
        "scopes": [        
            "read"      
        ]    
    }  
}'

Note: 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:

{
  "token": {
    "url": "https://{domain}.zendesk.com/api/v2/oauth/tokens/{token_id}.json",
    "id": {token_id},
    "user_id": {user_id},
    "client_id": {client_id},
    "token": {token},
    "refresh_token": null,
    "created_at": "2006-01-02T15:04:05Z",
    "expires_at": null,
    "used_at": null,
    "scopes": [
      "read"
    ],
    "full_token": "{full_token}"
  }
}

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

Integration with Birdie

Removal of private comments

By default, Birdie only imports tickets with atleast one public comment from Zendesk. Public comments are comments visible to both the end user and the company's agents. These tickets make up the majority of support interactions, allowing the customer to view agents’ responses and interact with them directly on the platform. Private comments are ignored by default, but the integration can be configured to import private tickets/comments as well.

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.

Ticket Import Process and Update Frequency

Birdie imports Zendesk tickets by checking for updates through the updated_at field, ensuring that the latest modifications are reflected in Birdie. This method enables Birdie to capture only the most recent changes without re-importing old data. We also support imports through Zendesk's Incremental API for cases when the ticket content may be updated but the updated_at field isn't. However, it’s important to note that this API method does not allow any pre-filtering through custom query filters.

Additional Entities for Enhanced Segmentation

Birdie also supports importing additional entities associated with tickets to improve segmentation. Below are the additional entities that can be imported:

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.

Custom Fields

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.