Users

Each user is one person who uses the service, an administrator, a device, or a fax machine.

User Parameters 

These are the parameters of the user object in our API that you can set, in the same order.

`pbx_location_id`

Default:: The first location of the account
Description:: The physical office location of the user. We use this information for these functions:

To identify the 911 information to send when the user dials 911
For location features such as Call Forward Location

`name`

Default:: empty
Description:: The full name of the user. We use it for the caller ID inside the organization and in rosters. Spaces are permitted.

`extension`

Default:: The next free extension
Description:: The extension that persons use to call the user or to send messages to the user. It must be unique in the account.

`username`

Default:: empty
Description:: The username of the user on the platform. We use it for identification. Other persons do not see it.

The username must be unique.
The username cannot be a phone number.
You can set the username only when you make the user. You cannot change it after.

`mailbox`

Default:: self
Description:: The primary mailbox of the user.
self:: We make a mailbox for the user if one does not exist. Then we assign that mailbox.
none:: The user does not have voicemail.
Any other value:: We assign the mailbox with that address to the user.

We give the primary mailbox special treatment:

When the user dials *86, we open only the primary mailbox.
Only messages in the primary mailbox turn on the message waiting indicator (MWI) of the devices.

Note

The voicemail PIN is a parameter of the mailbox, not of the user. Refer to Mailbox.

`sip_password`

Default:: A random password
Description:: The password that VoIP devices use to authenticate to the account of the user.

Important

Do not change this password unless you know the result. A change stops all devices that use the old password.

`password`

Default:: A random password
Description:: The password of the user. We never show the current password.

`pin`

Default:: A random 5-digit PIN
Description:: The PIN that the user types to authenticate to the OnCall platform.

This is not the voicemail PIN. The voicemail PIN is set on the mailbox.

This PIN is also the moderator_pin of the personal telemedicine rooms of the user.

`max_bindings`

Default:: 10
Description:: The maximum number of devices that the user can register at the same time. Do not change it unless you know the result.

`external_callerid_name`

Default:: empty
Description:: The caller ID name for outbound calls. It can be different from the name. If you leave it empty, the called person sees the CNAM of the number.

`external_callerid_number`

Default:: empty
Description:: The number that outbound calls come from. If you leave it empty, calls come from the caller ID of the location.

`email`

Default:: empty
Description:: The email address of the user. The user signs in to the portal with this address. We also send password resets to it.

If you change this address, the user must sign in with the new address.

Integrations also use this address to match the user to the same person in other connected systems. Keep it the same as the address in those systems.

`mobile`

Default:: empty
Description:: A different number that we can use to reach the user, usually a mobile phone. It can be a 10-digit external number or the extension of a different user. We use it with forward_behavior. For more information, refer to Mobile.

`call_timeout`

Default:: 24
Description:: The number of seconds that the phone rings before the call goes to voicemail. For sequential, it is also the time between the two steps. For more information, refer to Call Timeout.

`forward_behavior`

Default:: endpoint
Description:: How we send inbound calls. For more information, refer to Call Behavior.
endpoint:: Only the desk phones and the mobile app of the user ring.
simring:: The desk phones, the mobile app and the mobile number ring at the same time.
sequential:: The desk phones and the mobile app ring first. Then the mobile number rings.
forward:: Only the mobile number rings.

`fax_ext`

Default:: The default fax service of the account
Description:: The fax service that the user sends faxes from. The user can then send faxes from the portal and from the mobile app.

`vm_email_content`

Default:: empty
Description:: A list of email addresses, with commas between them. We send the voice file of each new voicemail message to these addresses. For more information, refer to Email to send voice message.

Important

Email of voice files is not HIPAA compliant.

`vm_email_notification`

Default:: empty
Description:: A list of email addresses, with commas between them. We send a notification to these addresses for each new voicemail message. For more information, refer to Email to send notifications.

`enable_mobile_stun`

Default:: false
Description:: Lets our mobile app use STUN to find its public network address. Do not change it unless you know the result.

`oncall_remind_minutes`

Default:: 60
Description:: The number of minutes before an OnCall shift starts that we send the reminder. For more information, refer to Notifications and Reminders.

`oncall_remind_email`

Default:: true
Description:: Sends an email reminder to the user before an OnCall shift starts.

`oncall_remind_sms`

Default:: true
Description:: Sends an SMS reminder to the user before an OnCall shift starts.

`oncall_notify_sms`

Default:: true
Description:: Sends an SMS to the user for each new OnCall message.

`oncall_notify_email`

Default:: true
Description:: Sends an email to the user for each new OnCall message.

`sms_enable`

Default:: false
Description:: Lets the user send and receive SMS messages. The user must also have an outbound_sms_number.

Important

SMS messages with PHI to devices that are not protected are not HIPAA compliant.

`outbound_sms_number`

Default:: empty
Description:: The number that SMS messages from the user come from. This applies only if sms_enable is true.

`mobile_signaling`

Default:: tls
Description:: The transport that our mobile app uses. Do not change it unless you know the result.

`call_recording`

Default:: The recording default of the account, else none
Description:: Sets which calls of the user we record. If your account does not have recording enabled, the value is always none.
none:: We do not record the calls of the user.
inbound:: We record only inbound calls to the user.
outbound:: We record only outbound calls from the user.
both:: We record all calls to and from the user.

This parameter also sets the default of record_conference for new personal telemedicine rooms of the user.

Important

Consult local laws about call recording before you set this.

`play_recording_announcement`

Default:: false
Description:: Plays a prompt on inbound calls to the user. The prompt tells the caller that we record the call.

`role`

Default:: user
Description:: The permissions of the user.
user:: The user can sign in to the portal, use the mobile app and use the other features of the system.
admin:: The user has all the rights of a user. The user can also change the account settings and make or delete configurations, including other users.
fax:: Use this role ONLY for a user that is bound to a fax machine. Do not set it manually.
device:: Use this role ONLY for a user that is bound to a shared device. We set fixed values for many parameters of a device user. Do not set it manually.

`billing_contact`

Default:: false
Description:: Makes the user a billing contact for the account. We send billing notifications to billing contacts.

`privacy_defender`

Default:: empty (off)
Description:: How we filter inbound calls. For more information, refer to Privacy Defender.
100:: DND. All calls go directly to voicemail.
99:: Contacts only. Only callers in the personal contacts of the user ring the phone. All other calls go to voicemail.
1:: Filter all. We filter all calls with the tele-captcha, whatever the spam risk.
2:: Filter low spam. We filter calls with a low or higher spam risk.
3:: Filter medium spam. We filter calls with a medium or higher spam risk.
4:: Filter high spam. We filter only calls with a high spam risk.
empty:: Off. We do not filter calls.

`pd_dont_filter_invalid_numbers`

Default:: false
Description:: When true, privacy_defender does not filter calls from numbers that are not valid.

`pd_dont_filter_tollfree_numbers`

Default:: false
Description:: When true, privacy_defender does not filter calls from toll-free numbers.

`sms_autoresp_enable`

Default:: false
Description:: Sends an automatic reply to inbound direct SMS messages.

`sms_autoresp_text`

Default:: empty
Description:: The text of the automatic reply.

Important

We send automatic replies ONLY to direct SMS messages. Group messages and internal messages do not get an automatic reply. We send a maximum of 1 automatic reply each hour to each phone number. This limit counts replies from text message rules and from the auto-responder together. Each new message from that number starts the hour again. This prevents reply loops and spam. If a text message rule matches a message, the rule decides the reply and the auto-responder is not used.

`Text Message Rules`

The user’s own text message rules. They control texts sent to any phone number whose SMS Extension is this user: deliver with an automatic reply, or move to the user’s Spam folder. Each rule can apply always, weekly or one time.

The rules are in the Text Message Rules panel of the user. The panel shows after the user is saved. A user can have 50 rules at most. Users can also manage their own rules on the My Phone page.

The phone number rules are checked before the user rules, and a phone number rule that blocks a text stops it before the user rules. How rules work is described in detail here

Note

Send to Spam rules need a mailbox. If the user has no mailbox, texts that match a Send to Spam rule are discarded.

`hide_from_dial_by_name`

Default:: false
Description:: When true, the user is not in the dial by name directory.

`enable_telemedicine`

Default:: false
Description:: Lets the user own personal and one-time telemedicine rooms. Telemedicine must also be enabled on the account.

A user does not need this parameter to be a moderator of a shared room. Refer to Telemedicine.

`pbx_user_schedules`

Default:: empty
Description:: A list of rules that tell us how to reach the user during an OnCall shift. For more information, refer to How OnCall Rules work.

Each item has these parameters:

name:: The name of the rule.
oncall_behavior:: patch connects the caller to the user. relay gives the message to the user. The default is patch.
forward_behavior:: How we ring the user. It uses the same values as forward_behavior. The default is endpoint.
timeout:: The number of seconds that we ring the user. The default is 24.
priority:: The order of the rule when two rules apply at the same time. The default is 1.
day_sun:: The rule applies on Sunday. The parameters day_mon, day_tue, day_wed, day_thu, day_fri and day_sat apply to the other days.
start_time:: The time of day that the rule starts. The default is 00:00:00.
end_time:: The time of day that the rule stops. The default is 23:59:00.
start_at:: The date and time that the rule starts. Use it with end_at.
end_at:: The date and time that the rule stops. When start_at and end_at are set, we ignore the days and the times of day.

When two or more rules apply, we use the rule that covers the shortest time first. Then we use the priority.

`pbx_mailbox_users`

Default:: empty
Description:: A list of the shared mailboxes of the user. Each item gives the user access to one more mailbox. For more information, refer to Mailbox Delegations.

Each item has these parameters:

pbx_mailbox_id:: The mailbox to share.
priority:: The order of the mailbox in the list of the user.

Avatar 

The picture of the user. Upload or remove the picture on the user settings page. We show the avatar in the portal and in telemedicine meetings.

Number Blocking 

The user can block calls from specified numbers. Each block rule has a phone number, a block action and an expiry time. For more information, refer to Blacklist.

Two Factor Authentication 

When otp_required_for_login is true, the user must type a one-time passcode (OTP) and the password to sign in. For more information about how this affects token requests, refer to API Authentication.

Use Generate TOTP URL on the user settings page to connect an authenticator app:

Type the current password.
Scan the code with the authenticator app.
Type the OTP code from the app.

API Keys 

Each user can make one or more API keys. An API key lets a program use our API without the username and the password. Use API keys for machine-to-machine integrations, scripts and all automation that has no person present. An API key does not put the sign-in credentials of the user into a program. You can revoke an API key and not change the password.

An API key has two parts:

Token:: A public identifier for the key. The token is always visible. Use it to identify the key when you list or delete keys.
Secret:: The private part of the key. Use it with the token to authenticate.

Important

We show the secret only one time, when we make the key. You cannot see the secret again. Keep the secret in a safe location immediately. If you lose the secret, delete the key and make a new key.

An API key belongs to the user who made it. It has the role and the permissions of that user. A key from an admin user can do admin actions. A key from a user can do only the actions of that user. When you remove the user or delete the key, the key stops immediately.

Managing API Keys 

The signed-in user manages API keys under the user settings (“My Phone”). These operations are available. Swagger gives the full details.

List keys:: GET /myphones/api_key gives a list of the keys of the current user. It gives only the token of each key. It never gives the secrets.
Create a key:: POST /myphones/api_key with a name in the body makes a new key. It gives the token and the secret. This is the only time that we show the secret.
Delete a key:: DELETE /myphones/api_key/{token} revokes the key with that token. All integrations that use the key stop immediately.

For the procedure to exchange a token and a secret for an access token, refer to API Authentication.