Users

About Users

Users represent just that, your users of the system. You can assign multiple devices to a user, put the user in a callflow, and all devices will ring.

Schema

Schema for a user

Key Description Type Default Required
call_forward The device call forward parameters object false
call_forward.direct_calls_only Determines if the calls that are not directly sent to the device should be forwarded boolean false false
call_forward.enabled Determines if the call forwarding should be used boolean false false
call_forward.failover Enable the call-forwarding parameters if the device is offline boolean false false
call_forward.ignore_early_media The option to determine if early media from the call forwarded number should ignored boolean true false
call_forward.keep_caller_id Determines if the caller id is kept when the call is forwarded, if not the devices caller id is used boolean true false
call_forward.number The number to forward calls to string(0..35) false
call_forward.require_keypress Determines if the callee is prompted to press 1 to accept the call boolean true false
call_forward.substitute Determines if the call forwarding replaces the device boolean true false
call_restriction Device level call restrictions for each available number classification object {} false
call_waiting #/definitions/call_waiting false
caller_id The device caller ID parameters object {} false
contact_list Contect List Parameters object {} false
contact_list.exclude If set to true the device is excluded from the contact list boolean false
dial_plan A list of rules used to modify dialed numbers object {} false
directories Provides the mappings for what directory the user is a part of (the key), and what callflow (the value) to invoke if the user is selected by the caller. object false
do_not_disturb DND Parameters object false
do_not_disturb.enabled Is do-not-disturb enabled for this user? boolean false
email The email of the user string(1..254) false
enabled Determines if the user is currently enabled boolean true false
feature_level The user level for assigning feature sets string false
first_name The first name of the user string(1..128) true
hotdesk The user hotdesk parameters object {} false
hotdesk.enabled Determines if the user has hotdesking enabled boolean false false
hotdesk.id The users hotdesk id string(0..15) false
hotdesk.keep_logged_in_elsewhere Determines if user should be able to login to mutliple phones simultaneously boolean false false
hotdesk.pin The users hotdesk pin number string(4..15) false
hotdesk.require_pin Determines if user requires a pin to change the hotdesk state boolean false false
language The language for this user string false
last_name The last name of the user string(1..128) true
media The device media parameters object {} false
media.audio The audio media parameters object {} false
media.audio.codecs A list of audio codecs the device supports array(string('OPUS', 'CELT@32000h', 'G7221@32000h', 'G7221@16000h', 'G722', 'speex@32000h', 'speex@16000h', 'PCMU', 'PCMA', 'G729', 'GSM', 'CELT@48000h', 'CELT@64000h', 'G722_16', 'G722_32', 'CELT_48', 'CELT_64', 'Speex', 'speex')) ["PCMU"] false
media.audio.codecs.[] string false
media.bypass_media Default bypass media mode boolean, string('true', 'false', 'auto') false
media.encryption Encryption Parameters object {} false
media.encryption.enforce_security Is Encryption Enabled? boolean false false
media.encryption.methods Supported Encryption Types array(string('zrtp', 'srtp')) [] false
media.encryption.methods.[] string false
media.fax_option Is T.38 Supported? boolean false
media.ignore_early_media The option to determine if early media from the device should always be ignored boolean false
media.progress_timeout The progress timeout to apply to the device (seconds) integer false
media.video The video media parameters object {} false
media.video.codecs A list of video codecs the device supports array(string('H261', 'H263', 'H264', 'VP8')) [] false
media.video.codecs.[] string false
metaflows The device metaflow parameters #/definitions/metaflows false
music_on_hold The music on hold parameters used if not a property of the device owner object {} false
music_on_hold.media_id The ID of a media object that should be used as the music on hold string(0..128) false
password The GUI login password string false
presence_id Static presence ID (used instead of SIP username) string false
priv_level The privilege level of the user string('user', 'admin') user false
profile User's profile data object {} false
pronounced_name Name pronounced by user to introduce himself to conference members object false
pronounced_name.media_id The ID of a media object that should be used as the music on hold string(0..128) false
qubicle #/definitions/qubicle_recipients false
require_password_update UI flag that the user should update their password. boolean false false
ringtones Ringtone Parameters object {} false
ringtones.external The alert info SIP header added when the call is from internal sources string(0..256) false
ringtones.internal The alert info SIP header added when the call is from external sources string(0..256) false
timezone User's timezone string false
username The GUI login username - alpha-numeric, dashes, at symbol, periods, plusses, and underscores allowed string(1..256) false
verified Determines if the user has been verified boolean false false
vm_to_email_enabled Determines if the user would like voicemails emailed to them boolean true false
voicemail object false
voicemail.notify object false
voicemail.notify.callback #/definitions/notify.callback false
call_waiting

Parameters for server-side call waiting

Key Description Type Default Required
enabled Determines if server side call waiting is enabled/disabled boolean false
caller_id

Defines caller ID settings based on the type of call being made

Key Description Type Default Required
emergency The caller ID used when a resource is flagged as 'emergency' object false
emergency.name The caller id name for the object type string(0..35) false
emergency.number The caller id name for the object type string(0..35) false
external The default caller ID used when dialing external numbers object false
external.name The caller id name for the object type string(0..35) false
external.number The caller id name for the object type string(0..35) false
internal The default caller ID used when dialing internal extensions object false
internal.name The caller id name for the object type string(0..35) false
internal.number The caller id name for the object type string(0..35) false
dialplans

Permit local dialing by converting the dialed number to a routable form

Key Description Type Default Required
system List of system dial plans array() false
metaflow

A metaflow node defines a module to execute, data to provide to that module, and one or more children to branch to

Key Description Type Default Required
children Children metaflows object false
children./.+/ #/definitions/metaflow false
data The data/arguments of the metaflow module object false
module The name of the metaflow module to execute at this node string(1..64) true
metaflows

Actions applied to a call outside of the normal callflow, initiated by the caller(s)

Key Description Type Default Required
binding_digit What DTMF will trigger the collection and analysis of the subsequent DTMF sequence string('1', '2', '3', '4', '5', '6', '7', '8', '9', '0', '*', '#') * false
digit_timeout How long to wait between DTMF presses before processing the collected sequence (milliseconds) integer false
listen_on Which leg(s) of the call to listen for DTMF string('both', 'self', 'peer') false
numbers A list of static numbers with their flows object false
numbers./^[0-9]+$/ #/definitions/metaflow false
patterns A list of patterns with their flows object false
patterns./.+/ #/definitions/metaflow false
notify.callback

Schema for a callback options

Key Description Type Default Required
attempts How many attempts without answer will system do integer false
disabled Determines if the system will call to callback number boolean false
interval_s How long will system wait between call back notification attempts integer false
number Number for callback notifications about new messages string false
schedule Schedules interval between callbacks array(integer) false
timeout_s How long will system wait for answer to callback integer false
profile

Defines user extended properties

Key Description Type Default Required
addresses To specify the components of the addresses array(object) false
addresses.[].address To specify the address string false
addresses.[].types To specify types of the address array() false
assistant To specify the user's assistant string false
birthday To specify the birth date of the user string false
nicknames To specify the text corresponding to the nickname of the user array(string) false
nicknames.[] string false
note To specify supplemental information or a comment that is associated with the user string false
role To specify the function or part played in a particular situation by the user string false
sort-string To specify the family name or given name text to be used for national-language-specific sorting of the FN and N types string false
title To specify the position or job of the user string false

Fetch summary of users in account

GET /v2/accounts/{ACCOUNT_ID}/users

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN} \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users
{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "email": "user1@account_realm.com",
            "features": [
                "caller_id",
                "vm_to_email"
            ],
            "first_name": "User",
            "id": "{USER_ID}",
            "last_name": "One",
            "priv_level": "admin",
            "timezone": "America/Los_Angeles",
            "username": "user1@account_realm.com"
        },
        {
            "email": "user2@account_realm.com",
            "features": [
                "caller_id",
                "vm_to_email"
            ],
            "first_name": "User",
            "id": "{USER_ID}",
            "last_name": "Two",
            "priv_level": "user",
            "timezone": "America/Los_Angeles",
            "username": "user2@account_realm.com"
        }
    ],
    "page_size": 2,
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Create a new user

PUT /v2/accounts/{ACCOUNT_ID}/users

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN} \
    -H "Content-Type: application/json" \
    -d '{"data":{"first_name":"User", "last_name":"Three"}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "call_restriction": {},
        "caller_id": {},
        "contact_list": {},
        "dial_plan": {},
        "enabled": true,
        "first_name": "User",
        "hotdesk": {
            "enabled": false,
            "keep_logged_in_elsewhere": false,
            "require_pin": false
        },
        "id": "{USER_ID}",
        "last_name": "Three",
        "media": {
            "audio": {
                "codecs": [
                    "PCMU"
                ]
            },
            "encryption": {
                "enforce_security": false,
                "methods": []
            },
            "video": {
                "codecs": []
            }
        },
        "music_on_hold": {},
        "priv_level": "user",
        "profile": {},
        "require_password_update": false,
        "ringtones": {},
        "verified": false,
        "vm_to_email_enabled": true
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Remove a user

This request will return the current JSON object of the now-deleted user.

DELETE /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "call_restriction": {},
        "caller_id": {},
        "contact_list": {},
        "dial_plan": {},
        "enabled": false,
        "first_name": "User",
        "hotdesk": {
            "enabled": false,
            "keep_logged_in_elsewhere": false,
            "require_pin": false
        },
        "id": "{USER_ID}",
        "last_name": "Three",
        "media": {
            "audio": {
                "codecs": [
                    "PCMU"
                ]
            },
            "encryption": {
                "enforce_security": false,
                "methods": []
            },
            "video": {
                "codecs": []
            }
        },
        "music_on_hold": {},
        "priv_level": "user",
        "profile": {},
        "require_password_update": false,
        "ringtones": {},
        "verified": false,
        "vm_to_email_enabled": true
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Fetch a user

GET /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN} \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "call_restriction": {},
        "caller_id": {},
        "contact_list": {},
        "dial_plan": {},
        "enabled": true,
        "first_name": "User",
        "hotdesk": {
            "enabled": false,
            "keep_logged_in_elsewhere": false,
            "require_pin": false
        },
        "id": "{USER_ID}",
        "last_name": "Three",
        "media": {
            "audio": {
                "codecs": [
                    "PCMU"
                ]
            },
            "encryption": {
                "enforce_security": false,
                "methods": []
            },
            "video": {
                "codecs": []
            }
        },
        "music_on_hold": {},
        "priv_level": "user",
        "profile": {},
        "require_password_update": false,
        "ringtones": {},
        "verified": false,
        "vm_to_email_enabled": true
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Patch a user's doc

PATCH /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{"data":{"enabled":false}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "call_restriction": {},
        "caller_id": {},
        "contact_list": {},
        "dial_plan": {},
        "enabled": false,
        "first_name": "User",
        "hotdesk": {
            "enabled": false,
            "keep_logged_in_elsewhere": false,
            "require_pin": false
        },
        "id": "{USER_ID}",
        "last_name": "Three",
        "media": {
            "audio": {
                "codecs": [
                    "PCMU"
                ]
            },
            "encryption": {
                "enforce_security": false,
                "methods": []
            },
            "video": {
                "codecs": []
            }
        },
        "music_on_hold": {},
        "priv_level": "user",
        "profile": {},
        "require_password_update": false,
        "ringtones": {},
        "verified": false,
        "vm_to_email_enabled": true
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Change the user doc

This requires posting the full user's document in the request body

Sync: See the documentation on device sync for more info on check-sync. One can add the field "sync": true to the JSON document in order to attempt a check-sync on every registered device this user has.

POST /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{"data":{"first_name":"User","last_name":"Three","call_restriction":{},"caller_id":{},"contact_list":{},"dial_plan":{},"enabled":false,"hotdesk":{"enabled":false,"keep_logged_in_elsewhere":false,"require_pin":false},"media":{"audio":{"codecs":["PCMU"]},"encryption":{"enforce_security":false,"methods":[]},"video":{"codecs":[]}},"music_on_hold":{},"priv_level":"user","profile":{},"require_password_update":false,"ringtones":{},"verified":false,"vm_to_email_enabled":true}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "call_restriction": {},
        "caller_id": {},
        "contact_list": {},
        "dial_plan": {},
        "enabled": false,
        "first_name": "User",
        "hotdesk": {
            "enabled": false,
            "keep_logged_in_elsewhere": false,
            "require_pin": false
        },
        "id": "{USER_ID}",
        "last_name": "Three",
        "media": {
            "audio": {
                "codecs": [
                    "PCMU"
                ]
            },
            "encryption": {
                "enforce_security": false,
                "methods": []
            },
            "video": {
                "codecs": []
            }
        },
        "music_on_hold": {},
        "priv_level": "user",
        "profile": {},
        "require_password_update": false,
        "ringtones": {},
        "verified": false,
        "vm_to_email_enabled": true
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Fetch (or create) a vCard

vCard is a file format typically used in emails as a form of business card. Kazoo currently generates a 3.0 compatible vCard.

GET /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/vcard

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN} \
    -H "Accept: text/x-vcard"
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/vcard
BEGIN:VCARD
VERSION:3.0
FN:User Three
N:Three;User
END:VCARD

Remove the photo from the user

DELETE /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/photo

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

Fetch the user's photo, if any

Set the Accept header to either application/base64 or application/octet-stream to retrieve the picture's contents.

If the result is successful, you will want to pipe the response into a file.

GET /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/photo

curl -v -X GET \
    -H "Accept: application/base64" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/photo
[binary data]

Create or change the user's photo

Use application/octet-stream as the content type.

POST /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/photo

curl -v -X POST \
    -H "Content-Type: application/octet-stream" \
    --data-binary @/path/to/image.jpg \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/photo
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {},
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Execute a quick call

Ring user's devices; once answered, connect to {PHONE_NUMBER}

In this scenario, the user's devices are considered the callee while the {PHONE_NUMBER} side is considered the caller (helpful to know when debugging a call!).

Query string options:

Key Type Description
auto_answer boolean() Tells the SIP phone to auto-answer the call, if supported
cid-name string() Set the caller ID name (defaults to "Device QuickCall")
cid-number string() Set the caller ID number (defaults to the {PHONE_NUMBER})
ignore-early-media boolean() Toggle whether to ignore early media
media string('bypass', 'process') Toggle whether to go peer-to-peer(bypass with the RTP
number_filter boolean(), regex() If true, remove non-alphanumeric characters. If a regex, use the first capture group as the "number" to dial.
timeout integer(3..) In seconds, how long to ring the device(s) (defaults to 30)

GET /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/quickcall/{PHONE_NUMBER}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/quickcall/{PHONE_NUMBER}
{
  "auth_token": "{AUTH_TOKEN}",
  "data": {
    "export_custom_channel_vars": [
      "Account-ID",
      "Retain-CID",
      "Authorizing-ID",
      "Authorizing-Type"
    ],
    "custom_channel_vars": {
      "authorizing_id": "{USER_ID}",
      "authorizing_type": "user",
      "inherit_codec": "false",
      "retain_cid": "true",
      "account_id": "{ACCOUNT_ID}"
    },
    "continue_on_fail": false,
    "dial_endpoint_method": "simultaneous",
    "outbound_callee_id_number": "{DEVICE_CALLER_ID_NUMBER}",
    "outbound_callee_id_name": "{DEVICE_CALLER_ID_NAME}",
    "outbound_caller_id_number": "{E164_NUMBER}",
    "outbound_caller_id_name": "Device QuickCall",
    "media": "process",
    "ignore_early_media": true,
    "timeout": 30,
    "endpoints": [
      {
        "outbound_call_id": "{CALL_ID}-quickcall",
        "custom_channel_vars": {
          "auto_answer": true,
          "authorizing_id": "{USER_ID}",
          "owner_id": "{USER_ID}",
          "account_id": "{ACCOUNT_ID}",
          "media_encryption_enforce_security": false,
          "sip_invite_domain": "{ACCOUNT_REALM}"
        },
        "custom_sip_headers": {
          "x_kazoo_aor": "sip:{DEVICE_SIP_USER}@{ACCOUNT_REALM}"
        },
        "presence_id": "{PRESENCE_ID}",
        "codecs": [
          "PCMU",
          "PCMA"
        ],
        "endpoint_id": "{DEVICE_ID}",
        "to_did": "{E164_NUMBER}",
        "to_realm": "{ACCOUNT_REALM}",
        "to_username": "{DEVICE_SIP_USER}",
        "to_user": "{DEVICE_SIP_USER}",
        "invite_format": "username"
      }
    ],
    "application_data": {
      "route": "{PHONE_NUMBER}"
    },
    "application_name": "transfer"
  },
  "status": "success",
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}"
}

Edit this page here