Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
For all the APIs, CONNECT-DOMAIN refers to the domain name for the WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE platforms.
Production CONNECT-DOMAIN: https://connect.symphony.com/admin
Test CONNECT-DOMAIN: https://connect.uat.symphony.com/admin
Note: Headers have been omitted in this example.
For Multi-company-contacts, the contacts must be from the same network, for example, all from WeChat or all from WhatsApp. Cross-network rooms are not authorized.
Always use the Copy icon in the example field when copying examples. Manual copy and paste is known to cause data format errors.
1. Create a new WhatsApp contact (use the Add a contact and/or advisors to a contact API).
2. Create a room (use the Create room API).
3. Add the new contact to the room (use the Add room member API).
4. Symphony Connect Helper sends the welcome message template to the new contact.
5. Check whether:
The message "We couldn’t add to this room as their WhatsApp account was not found" is sent in the room. OR
In the WhatsApp Connect app, the contact’s card shows the status UNAVAILABLE (if using a bot, check for "status": "UNAVAILABLE"
in the API response).
6. If the contact’s status is UNAVAILABLE:
The contact does not have the WhatsApp app, and you should remove them.
If they're the last contact in the room, this will deactivate the room.
Ask the user to create a WhatsApp account or provide their correct phone number and retry the onboarding.
7. If the contact’s status is different from UNAVAILABLE (see the Contact status section):
The contact has the WhatsApp app, and you can continue the flow as usual.
No status will be returned if the contact is created without being added to a room.
Available permissions as of release 23.07
By default, when an Advisor is entitled, they are assigned the following permissions: create:room
, create:contact
, edit:contact
, delete:contact
, on-behalf:onboard
. These default permissions are configurable.
Prior to any calls, a customer needs to provide **** at least one pem-encoded public key, associated with a name that will identify this key on the Connect platform (WECHAT, WHATSAPP, SMS, SMS-DIRECT or LINE). These two pieces of information will enable the customer to generate a Java Web Token (JWT) required with all calls to the Connect platform API endpoints.
For convenience, we provide below the sequence to create a RSA key pair:
For security reasons, the private key MUST NOT be shared. Symphony employees will not be asking for the private key.
Should you need to revoke the key or in case you have lost it, you can request its removal or replacement by opening a ticket with Symphony support.
The Connect platform requires the JWT token to include this specific information:
Note: This library is a dependency of the Symphony SDK, meaning that, if you are set up to work with Symphony APIs, you do not require any additional library.
Example: API call using Curl
PERMISSION | AVAILABILITY | DESCRIPTION |
---|---|---|
Always use the Copy icon in the example field when copying examples. Manual copy and paste is known to cause data format errors.
For more information on this authentication mechanism and the key pair format, please refer to the
The JWT must be provided by the caller as a Bearer Token in the Authorization header of each HTTP request (see ).
Example: Java using _io.jsonwebtoken:jjwt_** library** (, connect to preview)
create:room
SMS
SMS-Direct
LINE
Required to create a room. It also allows the user to use the Rooms tab to manage rooms: create a room, deactivate a room, add members, remove members, transfer room ownership. If the user doesn’t have the create:room
permission, the New room button is not displayed. (All users have access to the Rooms tab, even if they do not have the create:room
permission.)
create:contact
SMS
SMS-Direct
LINE
Required to create a contact via the Contacts tab. If the user doesn’t have the create:contact
permission, the New contact button is not displayed on the Contacts tab. (All users have access to the Contacts tab, even if they do not have the create:contact
permission.)
Users without the create:contact
permission will have contacts created each time they are added to rooms with new contacts. Also required (along with admin:list-customers
and on-behalf:onboard
) to add new advisor connections to a client from the Admin tab.
on-behalf:onboard
SMS
SMS-Direct
LINE
Enables the user to onboard contacts on behalf of other users. Also required (along with admin:list-customers
) to add a connection to a contact via the Admin tab.
edit:contact
SMS
SMS-Direct
LINE
Required to edit a contact via the Contacts tab. If the user doesn’t have the edit:contact
permission, the Edit contact option is not displayed in the Contacts tab. A contact’s first and last name cannot be edited if the contact has already been added to WhatsApp Connect by another user. The company name cannot be edited if the contact is already a participant in a chat room. The email address and telephone number cannot be edited. Also required (along with admin:list-customers
and on-behalf:onboard) to edit client contact details from the Admin tab.
edit:contact-email
SMS
SMS-Direct
LINE
Required to edit a contact email via the Contacts tab or the Admin tab. If the user doesn’t have the edit:contact-email
permission, the email address field of the Edit contact form is disabled in the Contacts tab, and so the email cannot be modified. An email address cannot be modified to the same value of another contact email address already existing in the contacts list.
delete:contact
SMS
SMS-Direct
LINE
Required to delete a contact via the Contacts tab. If the user doesn’t have the delete:contact
permission, the Remove contact option is not displayed in the Contacts tab. This permission is not required to delete a contact in the Admin tab.
on-behalf:simple-offboard
SMS
SMS-Direct
LINE
Required to offboard a contact or to remove a connection from a user via the Admin tab (along with admin:list-customers
). This permission is not required to remove a contact via the Contacts tab.
admin:list-customers
SMS
SMS-Direct
LINE
Gives the user access to the Admin tab, which displays all contacts onboarded for the current tenant and allows the user to add a contact to an existing room, view rooms a contact is part of, and view a given contact’s advisor connections. Additional permissions required for additional functionalities on the Admin tab:
To offboard a contact or remove a connection from an advisor via the Admin tab, the user requires the on-behalf:simple-offboard
permission in addition to the admin:list-customers
.
To create new contacts on behalf of advisors from the Admin tab, the user requires both the create:contact
and the on-behalf:onboard permissions.
To edit contact details, the user requires both the edit:contact
and on-behalf:onboard
permissions.
add:multi-company-contact
SMS
SMS-Direct
LINE
Allows the user to participate in a room with contacts from different companies. Requires the create:room
permission.
create:own-external-contact
Allows the user to configure and activate their own WhatsApp account, and add it to rooms.
create:colleague-contacts
Allows the user to create the WhatsApp contact of someone in the same company, based on their WhatsApp profile.
enable:voice-calls
SMS-Direct
Required to place and receive phone calls for virtual numbers. If a user does not have this permission, the call button is not displayed in SMS-Direct rooms.
This permission does not affect business numbers, and no call button will be displayed in Symphony for such numbers, as business number calls can be placed and received only though the phone's native devices.
Once enabled for an external network, the contact preferred language can be set and updated for users through the customer endpoint dedicated to contact management.
In this list, each valid language name is associated with a language code. The convention we use for setting the contact preferred language is full language names from the list, for example, French, German, Japanese, etc. Language name options including a code between parentheses are written with an underscore instead of parentheses, for example, English_UK, Chinese_CHN, Chinese_TAI.
The contact status provides information on a user’s onboarding status. The value of the status can vary and depends of the external network on which the user is onboarded.
Note: Contact statuses are only used for LINE, WeChat, SMS & Voice Direct and WhatsApp contacts.
Available contact statuses are:
Always use the Copy icon in the example field when copying examples. Manual copy and paste is known to cause data format errors.
The list of supported preferred languages is based on Meta's Supported Languages list, available at .
Always use the Copy icon in the example field when copying examples. Manual copy and paste is known to cause data format errors.
Contact status | Availability | Description |
---|
PENDING_CONFIRMATION |
| The invitation email was sent, but the contact did not validate their onboarding yet. |
CONFIRMED |
| The invitation email was sent and the contact used it to validate their onboarding.
|
INVITE_EXPIRED |
| The invitation email was sent, but the delay for the contact to validate their onboarding through the invitation was exceeded. |
UNAVAILABLE |
| The contact's phone number is not valid for the external network. Note: For WhatsApp, the contact status is either empty or UNAVAILABLE. The UNAVAILABLE status will only appear if the WhatsApp contact has already been added to a room, as we need to send the welcome template at least once to check if the contact’s phone number is valid. Once the contact’s status is set to UNAVAILABLE, the only way to change this state is by removing and creating the contact again. |
INCOMPLETE |
| A contact who is not in a Symphony user's contact list is automatically onboarded after sending a message or making a call to the Symphony user's second (or virtual) number. |
BLOCKED |
| A contact who cannot be automatically onboarded; a Symphony user needs to onboard or unblock them. |
Always use the Copy icon in the example field when copying examples. Manual copy and paste is known to cause data format errors.
Always use the Copy icon in the example field when copying examples. Manual copy and paste is known to cause data format errors.
1. Create a new LINE contact (use the Add a contact and/or advisors to a contact API).
If the contact is onboarded for the first time, they will receive an invitation email with complete instructions on how to authenticate their identity via the LINE app.
Check if the user has completed their onboarding:
In the LINE Connect app: Check if the contact’s card shows the status CONFIRMED.
Using the List or search for contact API: Look for "status": "CONFIRMED"
in the API response.
2. Create a room (use the Create room API).
3. Get the available LINE channels (also known as LINE Official Accounts) that can be used to communicate with the contact in the room (use List available channel connectors API). This is not required if the LINE channel automatic selection is enabled for your company of federation group.
4. Add the new contact to the room, specifying one available LINE channel (LINE Official Account) ID (use the Add room member API). To trigger automatic LINE channel selection (if enabled for your company or federation group), keep the LINE channel field empty.
The contact will receive a push message, inviting them to add the automatically or manually selected LINE official account as a friend in the LINE app.
Manual onboarding
1. Create a new SMS-DIRECT contact (use the Add a contact and/or advisors to a contact API).
2. Symphony Connect Helper creates a room with the contact.
3. Symphony Connect Helper sends the welcome message template to the new contact.
4. The contact has an SMS conversation on their phone. You can continue the flow as usual.
Symphony users sending a SMS message to a US-based contact for the first time will trigger an opt in/opt out step, in line with the requirements laid out in the Telephone Consumer Protection Act of 1991 (“TCPA”). The contact cannot receive the first message sent by the Symphony user until they explicitly opt in to communicate via the channel.
'On-the-fly' onboarding (inbound message)
1. A Symphony user receives an unsolicited SMS or phone call from a phone number (an SMS-DIRECT number) that is not associated with any existing contact in their list.
2. A new incomplete contact is created ‘on-the-fly’ in the contact list.
In the SMS & Voice Direct extension app (Symphony Desktop), the contact’s card shows an INCOMPLETE status and only displays the phone number. The contact's name and details can be edited afterwards.
3. Symphony Connect Helper creates a room with the contact.
4. Symphony Connect Helper sends a welcome message to the contact. You can continue the flow as usual.
Always use the Copy icon in the example field when copying examples. Manual copy and paste is known to cause data format errors.
Always use the Copy icon in the example field when copying examples. Manual copy and paste is known to cause data format errors.
Always use the Copy icon in the example field when copying examples. Manual copy and paste is known to cause data format errors.
Always use the Copy icon in the example field when copying examples. Manual copy and paste is known to cause data format errors.
Always use the Copy icon in the example field when copying examples. Manual copy and paste is known to cause data format errors.
List all permissions available for the external network at "CONNECT-DOMAIN" For each permission, returns id, name and whether they are set by default or not
The external network.
List of EMP permissions found
Remove phone number's address
Phone number
The phone number's address has been successfully removed
List the available entitlements.
List of found entitlements
List of available permissions for the external network at "CONNECT-DOMAIN"
List of permissions found
Remove an advisor's contact searching by the advisor's Symphony user ID and the contact's Symphony user ID
Advisor's Symphony user ID
Contact's Symphony user ID
Contact successfully removed
Get phone address
Phone number
Found phone address
Search for companies by name. Note: The WeChat or WhatsApp or SMS or SMS Direct or LINE onboarding applications do not enforce consistency for company names.
Start of the company's name to match
List of found companies
Update a room's features. Only supported for WhatsApp. The room is identified by its streamID.
Room's streamId. The streamId needs to be URLsafe Base64. To obtain the URLSafe Base64 conversation ID:
Allows to enable or disable attachments in a room. Only supported for WhatsApp.
Features updated successfully
Get information on a phone number provided by Symphony
Phone number provided by Symphony
Found phone number provided by Symphony
List the permissions granted to an advisor on an external network.
Advisor's Symphony user ID
The external network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
List of advisor's permissions
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
Removes a given advisor's entitlement for a given external network. Advisors can be identified using their email address or their Symphony user ID (if both are provided, the Symphony user ID will take precedence)
Advisor's email address
Symphony user ID
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
The entitlement has been successfully removed.
Transfer the room ownership to the advisor matching the provided Symphony user ID. This advisor should already be a member of the room.
StreamId of the room to transfer.
Room owner updated successfully
Update phone number's address
Phone number
The phone number's address has been successfully updated
Remove a permission from an advisor.
Advisor's Symphony user ID
The external network
permissionName to remove
Permission successfully removed
Remove the contact from all the advisors they are connected to for a given external network.
Contact's Symphony user ID
Contact found. The response includes a status report (SUCCESS or FAILURE) of the connection removal for each advisors initially connected to the contact.
Only applicable for networks requiring onboarding invitations: WeChat, LINE. Sends a new onboarding invitation to the contact with the onboarding instructions and a new authentication one-time-password token, if applicable. Required to reset the contact's invitation after it expires. The invitation expiry counter (7 days) is reset to zero and the status is changed from "Expired" to "Pending". LINE since 23.04: If the user enters an expired one-time-password token within the first 7 days they were onboarded, they automatically receive a new valid token. After the 7 days, calling this api is required to reset the user invitation status and to generate a new token.
Contact's Symphony user ID
Onboarder's Symphony user ID
The invite has been resent successfully.
Remove an advisor pre-entitlement Supported on WhatsApp Direct only
Symphony User Id
External network: WHATSAPP-DIRECT
The pre-entitlement has been removed successfully.
Remove specific advisor-contact connections in bulk.
Contacts found. The response includes a status report (SUCCESS, NOT_FOUND or FAILURE) of the connection removal for each advisor initially connected to each contact in the array of objects.
List all entitled advisors on a given external network.
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
The before cursor for pagination
The after cursor for pagination
List of found entitled advisors.
Phone number (direct EMP case)
Sub-network: IN-NETWORK or SECOND-NUMBER
Removes all contacts of an advisor matching the advisor's Symphony user ID.
Advisor's Symphony user ID
Call completed - Report provided with the list of SUCCESSFUL and FAILED operations
List all federation groups
The before cursor for pagination
The after cursor for pagination
List of federation groups
Internal system federation group identifier
Out facing customer display name
List of activated external network for the federation group
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
Update advisor's federation group for the given external network.
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
Advisor's Symphony user ID
The advisor's federation group is updated successfully.
List a room’s members. The room is identified by its streamID.
Room's streamId. The streamId needs to be URL safe Base64. To obtain the URLSafe Base64 conversation ID:
The before cursor for pagination
The after cursor for pagination
List of room members
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
Network channel connector used for room member. Only for LINE
Search for the advisors of a provided contact email address for a given external network.
The Contact's Symphony user ID
The before cursor for pagination
The after cursor for pagination
List of advisor(s) found
Phone number (direct EMP case)
Sub-network: IN-NETWORK or SECOND-NUMBER
Pre-allocate a phone number to an advisor to allow the advisor to activate their phone number. Supported on WhatsApp Direct only Umony numbers are not eligible for pre-entitlements. Symphony users using Umony numbers can skip the pre-entitlement step and be entitled directly.
Symphony User Id
External network: WHATSAPP-DIRECT
The phone number has been successfully allocated to the user.
Grant permission to an advisor.
Refer to the Permissions table on the Authentication page for the default permissions.
For multi-company contacts, the contacts must be from the same network, e.g. all from WeChat or all from WhatsApp. Cross-network rooms are not authorized.
Advisor's Symphony user ID
The external network
Permission successfully added to the advisor
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
List the EMP connectors available for one or multiple contacts by Symphony IDs
EMP connector corresponds to \
The external network: LINE or WHATSAPP or SMS
Contacts' Symphony IDs
Federation group ID
EMP connectors found
Grant permission to multiple advisors.
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
Permission successfully added to the advisor
Symphony user ID of the advisor
email adress of the advisor
Should an error occur while adding or removing the permission, this returned object will provide details about the error(s)
List all rooms where an advisor is either a member or an owner for a given network. Search is performed with the advisor's Symphony user ID. This end point returns at most 25 records per page.
Advisor's Symphony user ID
The external network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
If set to "true", lists the rooms where the advisor is an owner. If set to "false", lists the rooms where the advisor is an owner and the rooms where the advisor is only a member.
The before cursor for pagination
The after cursor for pagination
List of rooms found
Remove any member, advisor or contact from a room. The room is identified by its streamID.
Room's streamId. The streamId needs to be URLsafe Base64. To obtain the URLSafe Base64 Conversation ID:
The Symphony user ID of the member to remove
The Symphony user ID of the advisor who is removing the member
Member successfully removed from the room
List contacts, can query by emailAddress, phoneNumber or by contactSymphonyId or by advisorSymphonyId. If the advisor has the admin:list-customers permission, they will be able to retrieve all pod contacts for a given externalNetwork, or to see other advisor's list of contacts.
The external network: WHATSAPP, SMS, WECHAT, SMS-DIRECT, LINE or WHATSAPP-DIRECT
Contact's email address
Contact's phone number
Contact's Symphony user ID
The advisor's Symphony ID
The before cursor for pagination
The after cursor for pagination
Contact found
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
Advisors Symphony IDs
Set the federation group of a room.
StreamId of the room to transfer
The room's federation group has been updated successfully.
Rename a room with the new room name which is provided.
StreamId of the room to rename.
Room name updated successfully
Search for the contacts associated with the provided advisor’s Symphony user ID for a given external network.
The external network: WHATSAPP, SMS, WECHAT, SMS-DIRECT, LINE or WHATSAPP-DIRECT
Advisor's Symphony user ID
The before cursor for pagination
The after cursor for pagination
List of contacts(s) found
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
Create a new contact copy. Some contacts might be shared between tenants. Shared contacts updates are not allowed. This API allows to create a contact copy that is dedicated for the requesting tenant and that can be updated. Contacts that are created starting from the 23.03 release are already not shared between tenants. This API is dedicated for shared contacts created prior to the 23.03 release. Please note:
Contact's Symphony ID
Contact successfully copied
Symphony user ID of the account copy
StreamIds of the rooms in which the user's account has been replaced with the account copy.
Check if a given advisor is entitled for a given external network. Advisors can be identified using their email address or their Symphony user ID (if both are provided, the Symphony user ID will take precedence)
Symphony user email address
Symphony user ID
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
Advisor data (if an entitled advisor has been found)
Phone number (direct EMP case)
Sub-network: IN-NETWORK or SECOND-NUMBER
Bulk update advisor's federation group.
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
The advisor's federation group is updated successfully.
Context dependent identifier of the item
An absolute URI that identifies the problem type. When dereferenced, it SHOULD provide human-readable documentation for the problem type (e.g., using HTML).
A short, summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized); example: Service Unavailable
The HTTP status code generated by the origin server for this occurrence of the problem.
A human readable explanation specific to this occurrence of the problem.
An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
Entitle a Symphony user to use the external network.
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
Required for the advisor to access SMS Direct In-Network and supported for SMS Direct Second-Number. Supported for the advisor to access WhatsApp Direct. However, note that the advisor’s phone number is not applicable for onboarding the advisor to other external networks (WeChat, WhatsApp, SMS or LINE).
The user has successfully been added in the list of entitlements.
Phone number (direct EMP case)
Sub-network: IN-NETWORK or SECOND-NUMBER
Update a contact's first name, last name, company name (maximum 25 characters) and, if the advisor has the permission for this, the contact's email address for a given external network. Note: Updating a contact's phone number is not supported.
Contact's Symphony user ID
Contact preferred language. Refer to contact preferred language section at the beginning of this documentation for valid language name.
Contact successfully updated
Federated user Symphony id
Advisors Symphony IDs
Contact preferred language
Add a member to a room:
Room's streamId. The streamID needs to be URLsafe Base64. To obtain the URLSafe Base64 conversation ID:
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
Boolean indicating whether added member is an advisor (false) or a federated user (true)
ID of the Emp channel Connector to use to reach the federated user. Required for LINE in case automatic LINE channel selection feature is not enabled for your tenant, not applicable for the other external networks.
Member successfully added to the room
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
Network channel connector used for room member. Only for LINE
Create a room with the advisor whose Symphony user ID is provided. The advisor is set as a member. "externalNetworkRoomDisplayName" applies for WeChat only.
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
Room created successfully
Add multiple advisors and/or contacts to a room. An advisor must be entitled for the relevant external network. A contact must have already been onboarded.
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
Operation to add members to the room completed. Returns an object with the detail of each member's addition success or failure.
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
Network channel connector used for room member. Only for LINE
Context dependent identifier of the item
An absolute URI that identifies the problem type. When dereferenced, it SHOULD provide human-readable documentation for the problem type (e.g., using HTML).
A short, summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized); example: Service Unavailable
The HTTP status code generated by the origin server for this occurrence of the problem.
A human readable explanation specific to this occurrence of the problem.
An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
Add a contact and/or advisor(s) to the contact. This end point can be called in 2 situations:
Note
For SMS, LINE, WHATSAPP and WECHAT, the companyName is mandatory
For SMS, LINE, WHATSAPP and WECHAT, the emailAddress is mandatory
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE
A list of Symphony user IDs of the advisors to add the contact to.
Contact preferred language code
A list of email addresses of the advisor to whom the contact is to be added. For WeChat, an "onboarder" is an advisor with the permission "create:contact". For WhatsApp, SMS, SMS Direct and LINE, the permission is set by default.
If both advisorSymphonyIds and advisorEmailAddresses are empty, the contact will be added to the onboarder with this email address.
Can be set to false in order to prevent the room creation when onboarding a contact on SMS Direct or WhatsApp Direct. This parameter can't be set to true for WhatsApp, SMS, Wechat and LINE for now.
Contact added successfully
External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE