Chat API

Goals

If you are participating in the Zendesk messaging beta, some Chat APIs are not supported. See How Zendesk messaging impacts Chat APIs for more information.

To track the effect that Chat agents have on improving sales or completing website based goals, you can set a URL-based goal (such as page views of a pricing page) that matches the URL exactly or contains a certain parameter in the URL.

Goals can be set up to capture conversions based on agent first-touch or last-touch attribution. The attribution period can be between 1 to 30 days.

Note: Accounts have a maximum limit of 5 active Goals. An error message "Goals limit exceeded" will appear if you exceed the active Goal limit.

JSON Format

Goals are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
attribution_model string false false Describes the attribution model associated with the goal. One of "first_touch", "last_touch"
attribution_period integer false false Describes the attribution period in days for this goal. Range between "1" to "30"
description string false false The description of the goal
enabled integer false false Describes whether the goal is enabled
id integer true false The ID of the goal
name string false false The name of the goal
settings object false false The settings for the goal. Contains the conditions array. See Conditions
Conditions

The settings attribute contains a conditions array. The conditions array contains objects which represent individual conditions to be matched. If any single condition is met, the goal is considered to be fulfilled. Each object has the following attributes.

Name Type Read-only Description
type string no Describes the type of condition. Currently supports only "url"
operator string no Describes the operator used to compare if a goal is fulfilled. One of "equals", "contains"
value string no Describes the actual value to compare if a goal is fulfilled. If operator is specified as "equals", value should start with "http://" or "https://"
Example
 
{
  "attribution_model": "first_touch",
  "attribution_period": 30,
  "description": "A sample goal",
  "enabled": 1,
  "id": 1,
  "name": "Goal 1",
  "settings": {
    "conditions": [
      {
        "operator": "equals",
        "type": "url",
        "value": "http://cart.com/"
      },
      {
        "operator": "contains",
        "type": "url",
        "value": "cart"
      }
    ]
  }
}

List Goals
  • GET /api/v2/goals

This lists all the goals for your account.

Allowed for
  • Owner
  • Administrator
Using curl
 
curl https://www.zopim.com/api/v2/goals \
  -v -u {email_address}:{password}
Example Response
 
Status 200 OK

[
  {
    "attribution_model": "first_touch",
    "attribution_period": 30,
    "description": "A sample goal",
    "enabled": 1,
    "id": 1,
    "name": "Goal 1",
    "settings": {
      "conditions": [
        {
          "operator": "equals",
          "type": "url",
          "value": "http://cart.com/"
        },
        {
          "operator": "contains",
          "type": "url",
          "value": "cart"
        }
      ]
    }
  },
  {
    "attribution_model": "last_touch",
    "attribution_period": 15,
    "description": "A sample goal",
    "id": 2,
    "name": "Goal 2",
    "settings": {
      "conditions": [
        {
          "operator": "equals",
          "type": "url",
          "value": "http://zopim.com/"
        },
        {
          "operator": "contains",
          "type": "url",
          "value": "zopim"
        }
      ]
    }
  }
]

Create Goal
  • POST /api/v2/goals
Allowed for
  • Owner
  • Administrator
Using curl
 
curl https://www.zopim.com/api/v2/goals \
  -d '{
        "name" : "Goal 3",
        "description" : "A new goal",
        "enabled" : 1,
        "attribution_model" : "first_touch",
        "attribution_period": 15,
        "settings" : {
          "conditions": [
            {
              "operator": "equals",
              "type": "url",
              "value": "http://mysite.com/"
            }
          ]
        }
      }' \
  -v -u {email_address}:{password} \
  -X POST -H "Content-Type: application/json"
Example Response
 
Status 201 Created

{
  "attribution_model": "first_touch",
  "attribution_period": 30,
  "description": "A sample goal",
  "enabled": 1,
  "id": 1,
  "name": "Goal 1",
  "settings": {
    "conditions": [
      {
        "operator": "equals",
        "type": "url",
        "value": "http://cart.com/"
      },
      {
        "operator": "contains",
        "type": "url",
        "value": "cart"
      }
    ]
  }
}

Show Goal
  • GET /api/v2/goals/{goal_id}
Allowed for
  • Owner
  • Administrator
Parameters
Name Type In Required Description
goal_id integer Path true The ID of the goal
Using curl
 
curl https://www.zopim.com/api/v2/goals/{goal_id} \
  -v -u {email_address}:{password}
Example Response
 
Status 200 OK

{
  "attribution_model": "first_touch",
  "attribution_period": 30,
  "description": "A sample goal",
  "enabled": 1,
  "id": 1,
  "name": "Goal 1",
  "settings": {
    "conditions": [
      {
        "operator": "equals",
        "type": "url",
        "value": "http://cart.com/"
      },
      {
        "operator": "contains",
        "type": "url",
        "value": "cart"
      }
    ]
  }
}

Update Goal
  • PUT /api/v2/goals/{goal_id}
Allowed for
  • Owner
  • Administrator
Parameters
Name Type In Required Description
goal_id integer Path true The ID of the goal
Using curl
 
curl https://www.zopim.com/api/v2/goals/3 \
  -d '{"name": "Good goal"}' \
  -v -u {email_address}:{password}
  -X PUT -H "Content-Type: application/json"
Example Response
 
Status 200 OK

{
  "attribution_model": "first_touch",
  "attribution_period": 15,
  "description": "A mew goal",
  "enabled": 1,
  "id": 3,
  "name": "Good goal",
  "settings": {
    "conditions": [
      {
        "operator": "equals",
        "type": "url",
        "value": "http://mysite.com/"
      }
    ]
  }
}

Delete Goal
  • DELETE /api/v2/goals/{goal_id}
Allowed for
  • Owner
  • Administrator
Parameters
Name Type In Required Description
goal_id integer Path true The ID of the goal
Using curl
 
curl https://www.zopim.com/api/v2/goals/3 \
  -v -u {email_address}:{password} -X DELETE
Example Response
 
Status 204 No Content