Group calling
Group calling allows you, via our sendalert API, to place two or more people into a single voice call, essentially an on-demand conference. You can start a group call immediately, schedule it for later or defer it until such a time as it’s needed and then trigger it by sending an SMS with a keyword or by clicking on a web-link. See our “on-demand group calling” page for much more information and some useful examples.
To implement a group call you specify the ivrType ‘group’ and a few other items; these are explained below. You’ll also need to check out our sendalert API call and our Ivr pages.
ivrType: group
The group IVR plays the main message and waits for a PIN to be entered. If the PIN is wrong then an optional badpin message is played and the IVR repeats. When a good PIN is entered then a final optional message is played, after which the recipient is placed into the group conference.
PINs are used to ensure that there is actually a person on the end of the call (to avoid voicemail and so forth). PINs are specified as part of the ivr setup (see below) and can be as simple as ‘*’ to denote any key press, which is also the default if you do not specify an actual PIN to use.
If you specify a PIN other than ‘*’ for any key then you should include additionalContent with the following contentTags (the main message is provided by the normal content/storedContent items in the alert JSON) otherwise the called party will not know if their PIN entry was successful or not:
- badpin – played to the caller if their PIN is incorrect
- enter – played to the caller just before they enter the group call after entering a good PIN
As with all voice content these additional items can utilise Alerting Hub’s Text-to-Speech (TTS) capability.
| Parameter | Requirement | Default | Description |
|---|---|---|---|
| ivrAttempts | Optional | 1 | Number of times the call will be attempted, if the call is not placed into the group call. |
| ivrPin | Optional | * | Specifies the PIN that the recipient must enter to be allowed into the group call. A single * (star) means any key and can be used to simply ensure the recipient is actually present. |
| ivrNoPinAttempts | Optional | 1 | The number of times that the recipient will be asked for a PIN without any key presses being received. |
| ivrBadPinAttempts | Optional | 1 | The number of times that the recipient will be asked for a PIN when they have entered a previous bad PIN. |
| ivrPinAuthIssuer | Optional | None | Specifies the issuer name of a Google Authenticator compliant authentication code, previously setup using the createauth API call. If specified (along with the label counterpart) then the ivrPin value is ignored and the caller will be asked to provide the latest rolling authentication code. |
| ivrPinAuthLabel | Optional | None | Specifies the label name of a Google Authenticator compliant authentication code, previously setup using the createauth API call. |