Core Concepts
The Spoke Directory
Each item in the Spoke directory is called a directory entry. Spoke's core directory entry types are userWithAvailability, teamWithAvailability and device. If you have enabled our PBX augmentation feature, then a Directory can also contain trunkUser, trunkDevice and trunkGroup types - these are equivalent to the device type with some additional attributes for display and search purposes.
Devices
In Spoke, you can add a SIP Device as a standalone Device, and it will appear as an entry in a Spoke directory. In Spoke, a SIP Device only provides basic dialtone and call audio functionality. Rich functionality is available through Spoke's desktop and mobile softphone applications, and we recommend SIP devices are only used for common area or conference room phones.
Note: Spoke does not currently support adding a Twilio client as a standalone entry in the Spoke directory. Instead, Twilio clients are automatically created when you add a Spoke user and they sign in using the Spoke mobile or desktop applications.
Users
In Spoke, a User can have multiple callable endpoints, for example:
- a Mobile phone running the Spoke mobile application for iOS or Android
- a Desktop PC running the Spoke desktop application for MacOS or Android
- a SIP Device registered to the Twilio SIP Registrar or to a third party PBX interconnected via a SIP Trunk
When a call arrives on Spoke for a given User, Spoke will dial all endpoints associated with that User. The endpoint that is answered wins and Spoke automatically stops ringing the user's other endpoints. Additionally, the user can transparently move the call from one endpoint to another, enabling them to answer a call at their desk and continue it on their mobile phone when leaving the office.
Call Groups/Teams
A Team (or Call Group) in Spoke is analogous to a hunt group in traditional PBX systems. A Team consists of one or more User or Device members, and has business rules that define how a call is routed to those members, as well as what happens when the call goes unanswered. When a call arrives on Spoke for a Team, Spoke will automatically create a call offer flow that dials the members of the team based on those pre-defined rules. For User team members, the same dial rules apply, which means that when the call is offered to the User, all of the user's endpoints are dialled at once.
Company Contacts in Spoke
Company Contacts are external contacts that are managed via the Phonebooks and Contacts endpoints.
Spoke supports two types of phonebooks:
Company Contacts (Shared): Contacts in shared phonebooks are searchable and visible to all users of the Spoke application.Company Contacts (Assigned): Contacts in assigned phonebooks are searchable and visible only to the user who is assigned that phonebook.
All Company Contacts are searchable and visible in the Spoke application under the 'External' tab. They are not editable by end-users and must be managed through the Spoke API.
Company Contacts (Shared)
Shared company contacts are used where you do not need to restrict which users can access a contact.
You can create and manage multiple Shared phonebooks, these are searchable and visible to all users.
Company Contacts (Assigned)
Each Spoke User also has a phonebook that contains company contacts that only they can see or search. This is useful for use cases where you need to restrict which contacts a user has access to.
You manage a user's phonebook via the creating or updating a personal phonebook endpoint, using the user's email address as follows:
Code
Extensions
Every entry in the Spoke directory is assigned an extension number.
Extensions are the primary mechanism for connecting calls that have already been answered by another Twilio application (such as Studio) to entries in the Spoke Directory. We do not, however, use extensions for internal call routing.
Extensions are created and managed through the Spoke account portal, and can be assigned to any Device, Team or User in your account. Extensions are unique, and there is a one to one mapping between extension and directory entry.
Calls on Spoke
All Spoke calls involve a conference bridge; this allows us to support warm transfer, multi-party calls, recording and other functionality.
This means that when a call arrives on the Spoke platform, the incoming call is placed into a conference via <Dial><Conference>... TwiML. We then use Twilio's Create Call REST API to dial all endpoints based on the target of the incoming call (a Device, Team or User as described above). When the call is answered by one of the endpoints, all other calls are cancelled, and the "winning" call is placed into the same conference.