Directories

Directories

About Directories

Directories provide the ability to route a caller to a user by having the caller enter DTMF corresponding to the directory users’ first or last names (versus having to know the user’s extension).

Schema

Allow a caller to search for a user/device by name instead of extension/DID

KeyDescriptionTypeDefaultRequiredSupport Level
confirm_matchWhen one match is found, require caller to confirm the match before connectingboolean()truefalsesupported
flags.[]string()falsesupported
flagsFlags set by external applicationsarray(string())falsesupported
max_dtmfCap the number of DTMF characters collected from a caller, 0 for unlimitedinteger(0..)0falsesupported
min_dtmfHow many DTMF characters to collect from a caller before processing the directoryinteger(1..)3falsesupported
nameThe name of the directorystring(1..)truesupported
search_fieldsWhat user fields to search DTMF matches on`string(‘first_name’‘last_name’‘both’)`
sort_byWhat field to sort on in matching documents when a caller enters characters`string(‘first_name’‘last_name’)`last_namefalse

Fetch

GET /v2/accounts/{ACCOUNT_ID}/directories

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/directories
{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "id": "77dfb38ff2353624e35bf4df91acda94",
            "name": "SmartPBX Directory"
        }
    ],
    "page_size": 1,
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Remove a directory

DELETE /v2/accounts/{ACCOUNT_ID}/directories/{DIRECTORY_ID}

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/directories/{DIRECTORY_ID}

Fetch a directory listing

GET /v2/accounts/{ACCOUNT_ID}/directories/{DIRECTORY_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/directories/77dfb38ff2353624e35bf4df91acda94
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "confirm_match": false,
        "id": "77dfb38ff2353624e35bf4df91acda94",
        "max_dtmf": 0,
        "min_dtmf": 3,
        "name": "SmartPBX Directory",
        "sort_by": "last_name",
        "ui_metadata": {
            "origin": "voip",
            "ui": "monster-ui",
            "version": "3.23"
        }
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

It is possible to fetch the directory as a PDF for download (such as a company directory, a sales department directory, etc).

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Accept: application/pdf"
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/directories/{DIRECTORY_ID}
Streams back a PDF document.

If your client does not support setting the Accept header, you can append ?accept=pdf to the URI and Kazoo will pretend you sent the proper Accept header.

Add a user to the directory listing

Once you’ve created the directory, you can PATCH a user’s doc to add the user to the directory:

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Accept: application/pdf"
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}
    -d `{"data":{"directories":{"{DIRECTORY_ID}":"{CALLFLOW_ID}"}}}`

Here, {CALLFLOW_ID} is the ID of the callflow the user would like executed if they’re matched in the directory.