IVRs - Talk API - Zendesk Developer Portal

IVRs

Interactive voice response (IVR) uses keypad tones or speech recognition to route customers to the right agent or department, provide recorded responses for frequently asked questions, and deflect calls by allowing callers to switch the interaction to text. IVR is available on the Talk Professional and Enterprise plans. For more information, see Route incoming calls with IVR in the Talk Help Center.

IVR JSON Format

An IVR has the following properties:

Name	Type	Read-Only	Comment
id	integer	yes	The IVR ID
name	string	no	The name of the IVR
menus	array	no	The list of the IVR menus
phone_number_ids	array	no	The list of IDs of all the phone numbers configured with this IVR
phone_number_names	array	yes	The list of the names of all the phone numbers configured with this IVR

Example

{
  "id": 10001,
  "name": "IVR Menu",
  "menus": [
    {
      "id": 10001,
      "name": "Main menu",
      "default": true,
      "greeting_id": 10001,
      "routes": [
        {
          "id": 10001,
          "keypress": "0",
          "greeting": null,
          "action": "group",
          "options": {
            "group_ids": [
              10001
            ]
          },
          "option_text": "Support Group"
        }
      ]
    }
  ],
  "phone_number_ids": [],
  "phone_number_names": []
}

List IVRs

GET /api/v2/channels/voice/ivr.json

Allowed For

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/ivr.json \
  -v -u {email_address}:{password} -X GET

Example Response

Status: 200 OK

{
  "ivrs": [
    {
      "id": 10001,
      "name": "IVR Menu",
      "menus": [
        {
          "id": 10001,
          "name": "Main menu",
          "default": true,
          "greeting_id": 10001,
          "routes": [
            {
              "id": 10001,
              "keypress": "0",
              "greeting": null,
              "action": "group",
              "options": {
                "group_ids": [
                  10001
                ]
              },
              "option_text": "Support Group"
            }
          ]
        }
      ],
      "phone_number_ids": [],
      "phone_number_names": []
    },
  ],
  "next_page": null,
  "previous_page": null,
  "count": 1
}

Show IVR

GET /api/v2/channels/voice/ivr/{id}.json

Allowed For

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/ivr/{id}.json \
  -v -u {email_address}:{password} -X GET

Example Response

Status: 200 OK

{
  "ivr": {
    "id": 10001,
    "name": "IVR Menu",
    "menus": [
      {
        "id": 10001,
        "name": "Main menu",
        "default": true,
        "greeting_id": 10001,
        "routes": [
          {
            "id": 10001,
            "keypress": "0",
            "greeting": null,
            "action": "group",
            "options": {
              "group_ids": [
                360001381413
              ]
            },
            "option_text": "Support Group"
          }
        ]
      }
    ],
    "phone_number_ids": [],
    "phone_number_names": []
  }
}

Create IVR

POST /api/v2/channels/voice/ivr.json

Allowed For

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/ivr.json \
  -H "Content-Type: application/json" -d '{"ivr": {"name": "IVR Menu"}}' \
  -v -u {email_address}:{password} -X POST

Example Response

Status: 201 Created

{
  "ivr": {
    "id": 10001,
    "name": "IVR Menu",
    "menus": [
      {
        "id": 10001,
        "name": "Main menu",
        "default": true,
        "greeting_id": null,
        "routes": []
      }
    ],
    "phone_number_ids": [],
    "phone_number_names": []
  }
}

Update IVR

PUT /api/v2/channels/voice/ivr/{id}.json

Allowed For

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/ivr/{id}.json \
  -H "Content-Type: application/json" -d '{"ivr": {"name": "IVR Menu"}}' \
  -v -u {email_address}:{password} -X PUT

Example Response

Status: 200 OK

{
  "ivr": {
    "id": 10001,
    "name": "IVR Menu",
    "menus": [
      {
        "id": 10001,
        "name": "Main menu",
        "default": true,
        "greeting_id": null,
        "routes": []
      }
    ],
    "phone_number_ids": [],
    "phone_number_names": []
  }
}

Delete IVR

DELETE /api/v2/channels/voice/ivr/{id}.json

Allowed For

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/ivr/{id}.json \
  -v -u {email_address}:{password} -X DELETE

Example Response

Status: 200 OK

IVR Menu JSON Format

An IVR menu has the following properties:

Name	Type	Read-Only	Comment
id	integer	yes	The IVR menu ID
name	string	no	The name of the IVR menu
routes	array	yes	The list of the IVR menu routes
default	boolean	yes	Whether this is the default menu for the IVR
greeting_id	integer	no	The ID of the greeting associated with the IVR menu

Example

{
  "id": 10001,
  "name": "Main menu",
  "default": true,
  "greeting_id": 10001,
  "routes": [
    {
      "id": 10001,
      "keypress": "0",
      "greeting": null,
      "action": "group",
      "options": {
        "group_ids": [
          360001381413
        ]
      },
      "option_text": "Support Group"
    }
  ]
}

List IVR Menus

GET /api/v2/channels/voice/ivr/{ivr_id}/menus.json

Allowed For

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/ivr/{ivr_id}/menus.json \
  -v -u {email_address}:{password} -X GET

Example Response

Status: 200 OK

{
  "ivr_menus": [
    {
      "id": 10001,
      "name": "Main menu",
      "default": true,
      "greeting_id": 10001,
      "routes": [
        {
          "id": 10001,
          "keypress": "0",
          "greeting": null,
          "action": "group",
          "options": {
            "group_ids": [
              360001381413
            ]
          },
          "option_text": "Support Group"
        }
      ]
    }
  ],
  "next_page": null,
  "previous_page": null,
  "count": 1
}

Show IVR Menu

GET /api/v2/channels/voice/ivr/{ivr_id}/menus/{id}.json

Allowed For

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/ivr/{ivr_id}/menus/{id}.json \
  -v -u {email_address}:{password} -X GET

Example Response

Status: 200 OK

{
  "ivr_menu": {
    "id": 10001,
    "name": "Main menu",
    "default": true,
    "greeting_id": 10001,
    "routes": [
      {
        "id": 10001,
        "keypress": "0",
        "greeting": null,
        "action": "group",
        "options": {
          "group_ids": [
            360001381413
          ]
        },
        "option_text": "Support Group"
      }
    ]
  }
}

Create IVR Menu

POST /api/v2/channels/voice/ivr/{ivr_id}/menus.json

Allowed For

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/ivr/{ivr_id}/menus.json \
  -H "Content-Type: application/json" -d '{"ivr_menu": {"name": "Main Menu"}}' \
  -v -u {email_address}:{password} -X POST

Example Response

Status: 201 Created

{
  "ivr_menu": {
    "id": 10001,
    "name": "Main Menu",
    "default": false,
    "greeting_id": null,
    "routes": []
  }
}

Update IVR Menu

PUT /api/v2/channels/voice/ivr/{ivr_id}/menus/{id}.json

Allowed For

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/ivr/{ivr_id}/menus/{id}.json \
  -H "Content-Type: application/json" -d '{"ivr_menu": {"name": "Secondary Menu"}}' \
  -v -u {email_address}:{password} -X PUT

Example Response

Status: 200 OK

{
  "ivr_menu": {
    "id": 10001,
    "name": "Secondary Menu",
    "default": false,
    "greeting_id": null,
    "routes": []
  }
}

Delete IVR Menu

DELETE /api/v2/channels/voice/ivr/{ivr_id}/menus//{ivr_id}/menus/{id}.json

Allowed For

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/ivr/{ivr_id}/menus/{id}.json \
  -v -u {email_address}:{password} -X DELETE

Example Response

Status: 200 OK

IVR Route JSON Format

An IVR route has the following properties:

Name	Type	Read-Only	Comment
id	integer	yes	The IVR route ID
keypress	string	no	The keypress associated with the IVR route. See Valid IVR Route Keypress Values
action	string	no	The action that will be performed by the IVR route. See Valid IVR Route Options
options	array	no	The options for the IVR route depending on the action. See Valid IVR Route Options
greeting	string	yes	The name of the greeting assosiated with the IVR route
option_text	string	yes	A text describing the options of the route. Example: When the option is `group`, "option_text" will be the name of the associated group

Example

{
  "ivr_route":
  {
    "id": 10001,
    "keypress": "0",
    "greeting": null,
    "action": "group",
    "options": {
      "group_ids": [
        360001381413
      ]
    },
    "option_text": "Support Group"
  }
}

List IVR Routes

GET /api/v2/channels/voice/ivr/{ivr_id}/menus/{menu_id}/routes.json

Allowed For

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/ivr/{ivr_id}/menus/{menu_id}/routes.json \
  -v -u {email_address}:{password} -X GET

Example Response

Status: 200 OK

{
  "ivr_routes": [
    {
      "id": 10001,
      "keypress": "0",
      "greeting": null,
      "action": "group",
      "options": {
        "group_ids": [
          360001381413
        ]
      },
      "option_text": "Support Group",
    }
  ],
  "next_page": null,
  "previous_page": null,
  "count": 1
}

Show IVR Route

GET /api/v2/channels/voice/ivr/{ivr_id}/menus/{menu_id}/routes/{id}.json

Allowed For

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/ivr/{ivr_id}/menus/{menu_id}/routes/{id}.json \
  -v -u {email_address}:{password} -X GET

Example Response

Status: 200 OK

{
  "ivr_route": {
    "id": 10001,
    "keypress": "0",
    "greeting": null,
    "action": "group",
    "options": {
      "group_ids": [
        10001
      ]
    },
    "option_text": "Support Group",
  }
}

Create IVR Route

POST /api/v2/channels/voice/ivr/{ivr_id}/menus/{menu_id}/routes.json

Allowed For

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/ivr/{ivr_id}/menus/{menu_id}/routes.json \
  -H "Content-Type: application/json" -d '{"ivr_route": {"keypress": "1", "action": "group", "options": {"group_ids" : [10001]}}}' \
  -v -u {email_address}:{password} -X POST

Example Response

Status: 201 Created

{
  "ivr_route": {
    "id": 10002,
    "keypress": "1",
    "greeting": null,
    "action": "group",
    "options": {
      "group_ids": [
        10001
      ]
    },
    "option_text": "Support Group",
  }
}

Update IVR Route

PUT /api/v2/channels/voice/ivr/{ivr_id}/menus/{menu_id}/routes/{id}.json

Allowed For

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/ivr/{ivr_id}/menus/{menu_id}/routes/{id}.json \
  -H "Content-Type: application/json" -d '{"ivr_route": {"keypress": "2"}}' \
  -v -u {email_address}:{password} -X PUT

Example Response

Status: 200 OK

{
  "ivr_route": {
    "id": 10002,
    "keypress": "2",
    "greeting": null,
    "action": "group",
    "options": {
      "group_ids": [
        10001
      ]
    },
    "option_text": "Support Group",
  }
}

Delete IVR Route

DELETE /api/v2/channels/voice/ivr/{ivr_id}/menus//{ivr_id}/menus/{menu_id}/routes/{id}.json

Allowed For

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/ivr/{ivr_id}/menus/{menu_id}/routes/{id}.json \
  -v -u {email_address}:{password} -X DELETE

Example Response

Status: 200 OK

Valid IVR Route Keypress Values

Valid values for the keypress field are [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, *, #, default]

Valid IVR Route Actions

action	options
group	group_ids: array, valid group ids
voicemail	group_ids: array, valid group ids
phone_number	phone_number: string, valid phone number
textback	sms_text: string, text to be sent in the sms message textback_phone_number_id: integer, valid id of Text enabled phone number
menu	menu_id: integer, valid IVR menu id