In many call centers, agents use several different tools to work on their daily tasks, e.g a CRM or helpdesk like Zendesk and a telephony tool like babelforce. Many of these tools allow the user to change their presence status. To prevent agents from having to adjust their status in several of these tools, babelforce offers the possibility to map the agent status between the different systems.

If you want to map the status from babelforce to Zendesk, so that the agent only has to change their status in babelforce, you can find the explanation here.

In this article we cover the process to map agent statuses the other way around - from Zendesk Omnichannel to babelforce:

The logic on babelforce side

babelforce offers a special webhook to listen to events on Zendesk. Once this webhook is triggered from Zendesk side, we can carry out a babelforce task (via the Task Automation Platform) containing the action to change the presence status in babelforce. In some cases, the status in Zendesk and in babelforce are called differently. Also, babelforce does not offer the possibility to set another "green" status apart from "available".
That is why we offer a standard task template to to fully integrate with the omnichannel agent availability feature of zendesk.It is already prebuilt and works out of the box and it maps certain Zendesk statuses to statuses on babelforce. You find it in the tasks section of our manager app. It is called "v1.0.0_babelforce.webhook.zendesk.agent.status.json". However, you don't need to adjust anything on babelforce side. 

The logic of the status mapping is the following:

Now let's look at the Zendesk side:

Setting up the webhook in Zendesk

1. Go to the Zendesk Admin Center (clicking on the gear wheel in the left hand bar, then clicking on "Go to admin center)
   
   
   
   
2. Click on Apps and Integrations, then Webhooks
   
   
3. In the top right corner, click on Create webhook
   
   
4. You can now select from a list of predefined events to subscribe to. To follow our example, choose "Agent unified status changed":
   
   
   
   
5. Click on Next 
   
   
6. In the next step, we need to fill out a few details like shown below:
   
    
   We need to give our webhook a name and we also need to enter the endpoint we want to trigger. Therefore we need to configure the webhook URL:

How to construct the webhook URL

1. This is the base URL for using the webhook: "https://{my_env}.babelforce.com/api/v1/webhook/zendesk"
At the end of the URL, we need to specify which task template should be carried out whenever this endpoint is triggered.
In our case, we add "?templateId=webhook_map_talk_status"

Also, we want to specify the domain of our zendesk account.

The complete URL then looks like this:

https://{{my_env}}.babelforce.com/api/v1/webhook/zendesk?templateId=webhook_map_talk_status&zendesk_tenant=my_zendesk_domain&data=all

2. To finish the setup in Zendesk, we need to create a bearer token for babelforce using the following cURL:

curl --location --globoff 'https://{{my_env}}.babelforce.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username={{my_username}}' \
--data-urlencode 'password={{my_password}}' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'expires_in=-1'

Add this token on Zendesk side like shown in the screenshot below.
3. Now, you can test your webhook by clicking on Test webhook

4. The right hand side shows the response:

This is an extract of the response body:

 {
  "id":"0fe3d4a8-335b-4c3e-a63d-c38d153020e2",
  "session_id":"e18a7220-585b-4f84-8205-a527f9f78022",
  "customer_id":"6c2a2f9e-6dbd-4fc1-b9d3-cde3c7a6e80d",
  "created_at":1707901067470,
  "body":{
        "event":{
               "channel":"support",
               "updated_at":"2023-04-05T23:30:58.642630335Z",
               "new_state":"online",
               "previous_state":"offline"
         },
         "detail":{
               "agent_id":"10011",
               "version":"3",
               "account_id":"2"
         },
         "id":"01GX79ST1QX01C889XV42S2J5T",
         "time":"2023-05-10T23:31:58.642630335Z",
         "subject":"zen:agent:10011",
         "type":"zen:event-type:agent.state_changed",
         "account_id":2,
         "zendesk_event_version":"2022-11-06"
   },
   "type":"webhook.zendesk.agent_status",
   "state":"Scheduled",
   "actions":{
         "....}
} 

The babelforce task body explained:

We see that Zendesk sends us certain information that is needed for us to trigger the status change in babelforce:

1. This snippet shows us the new status the agent has
   "body":{
"event":{
"channel":"support",
"updated_at":"2023-04-05T23:30:58.642630335Z",
"new_state":"online",}
   
2. This part shows us, which agent we need to update:
   "detail":{
"agent_id":"10011",
"version":"3",
"account_id":"2"
},
   The agent id is the "source_id" of our agent in babelforce.
3. With this info in mind, we can now have a closer look again at a few parts of our task body:
   
   
   1. The URL of our 1st. http request:
      "url": "{{{env.babelforce.url}}}/api/v2/agents?sourceId={{{task.body.detail.agent_id}}}"
      We search for the agent in babelforce filtering for the source id that we got from Zendesk
   2. The body of our 2nd http request:
      "body": { "presence": { "name": "{{{task.body.event.new_state}}}" } },
      We set the status of the agent to the status that Zendesk returned to us as the "new state"

Storing the zendesk token

We don't want to expose the API token we use to authenticate against the zendesk endpoints. That is why we store it via our secrets API, and retrieve it via {{secret.zendesk.webhook}}

To store the token, there, you need to call
curl -X 'POST' \ 'https://{{env}}.babelforce.com/api/v3/tasks/configurations/secrets/zendesk' \ -H 'accept: */*' \ -H 'Authorization: Bearer i_MM***' \ -H 'Content-Type: application/json' \ -d '{ "webhook": "Basic YmFiZWxmb*****" }'

Create your zendesk statuses in babelforce 

To be able to synchronize your statuses, make sure to create the same "red" statuses in babelforce that you have in Zendesk.