Welcome to the ZenDesk documentation for Dimension! Integrating Dimension into your ZenDesk account is quick and easy.

Setting Up Zendesk API Access

Generate Zendesk API Token:

To create and share an API key log in to your Zendesk account. In Admin Center, click Apps and integrations in the sidebar, then select APIs > Conversations API and click Create API key.
If you are creating your first key, this button appears at the bottom of the page; if you have previously created a key, it appears in the top-right corner.
Enter an identifying name for the key in the Create new key dialog, then click Next.
In the Copy shared secret dialog, click Copy for each ID and secret key to save it to your clipboard, then click Next.
When you're returned to the API window, where the new key appears in the list.

Enable Token Access and create a new API token. Note this token down securely.

Base URL for Requests:

Your Zendesk API requests will use a base URL: https://{your_subdomain}.zendesk.com/api/v2

Replace {your_subdomain} with your actual Zendesk subdomain.

Accessing Data from Zendesk Endpoints

We will focus on three endpoints:

Conversations API: To fetch live chat conversations.

Endpoint: /api/v2/chats

Example GET request:

GET https://{your_subdomain}.zendesk.com/api/v2/chats
Authorization: Bearer {your_zendesk_api_token}

Tickets API: To fetch ticket information.

Endpoint: /api/v2/tickets

Example GET request:

GET https://{your_subdomain}.zendesk.com/api/v2/tickets
Authorization: Bearer {your_zendesk_api_token}

POST responses to Dimension

When you receive a message or support ticket post the data to the following endpoint:

https://tracker.dimensionlabs.io/track?platform=universal&v=10.1.1-rest&type=incoming&apiKey=API_KEY_HERE

Make sure to set the ‘Content-Type’ header to ‘application/json’ and to replace API_KEY_HERE with your api key.

You must send the data with the following fields:

text – string – (required)
userId – string – (required) – should be the SAME userId for both incoming and outgoing messages this is NOT the bot’s user ID

To review all optional fields see our API reference.

The data to POST should pass the following data:

{
  "text": "Hi, bot",
  "userId": "+14155551234",
  "platformJson": {
    "whateverJson": "any JSON specific to your platform can be stored here"
  }
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"text":"Hi, bot","userId":"+14155551234","platformJson":{"whateverJson":"any JSON specific to your platform can be stored here"}}'
     'https://tracker.dimensionlabs.io/track?platform=sms&v=11.1.0-rest&type=incoming&apiKey=API_KEY'

Notice, you must replace the placeholder API_KEY_HERE above with your api key.