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