Syniverse Chatbot Connector Service (Developer Preview)
The service allows Syniverse Cloud messaging customer to leverage SCG (Syniverse Communication Gateway) message delivery channels and provide connectivity to external entities which expose messaging APIs and for which this service has a corresponding API module (or plugin) in place.
Syniverse Connector Service
The Syniverse Connector service provides Customers Chatbot Service accounts hosted on Cloud platforms a dedicated connector that allows them to create and enable a Syniverse messaging channel for their Bot services to communicate with their end-users.
The service will provide REST endpoint “connectors” where the user will be able to do CRUD operations for its connectors. The connector entity will contain configuration information needed for the corresponding service instance to function, like:
- A dedicated Syniverse Sender ID (Messaging guide)
- API type e.g. (Direct Line API) or Google DialogFlow
- Configuration information about this API, like URLs (if not well known), credentials
- State - ACTIVE/INACTIVE
As soon as a connector is put by the user in state ACTIVE it will begin to function.
SCG_CONNECT_DEFAULT_CONVERSATION_IDLE_TIMEOUT (2 * 60)
After this time with no MO the conversation will be considered finished and will be closed. Subsequent message from the same user will open a new conversation.
Connector Service Integration
Connector service is now available for the following services:
MS Azure Cloud Connector
Using the MS Azure Bot Direct Line API to Syniverse Messaging services. The connector service is able to translate session-oriented APIs like the Direct Link into paging-oriented APIs like SMS, MMS by emulating session behavior based on a Syniverse Sender ID, end-user contact (MDN) and time. The service can also be used with other Syniverse Messaging Channels that are IP-based.
Google DialogFlow Connector
Google DialogFlow connectors can be used with the Syniverse Messaging channels. The Syniverse Connector service allows customers using DialogFlow to create their Chatbot to enable a Syniverse Channel to communicate with their end-users via any number of available channels. A Dialogflow account and Google Cloud platform credentials are required to use this connector. MTs are received as response to the request that sends the MO. Conversations are created implicitly.
Syniverse Messaging Channels for Connectors
The Syniverse Messaging channels that can be leveraged on the Syniverse connector service include:
- SMS
- Facebook Messenger
- RCS
Prerequisite to using the Syniverse Connector service
- Syniverse Cloud Messaging Account with a subscription to Voice and Messaging service (https://developer.syniverse.com )
- A valid Dedicated Sender ID (Can be a Shortcode, Longcode, or toll-free number. Can also be a Sender ID configured for RCS, WhatsApp or Facebook Messenger).
For Microsoft (MS) Azure Chatbots
- A configured Bot on the MS Azure Cloud portal (https://docs.microsoft.com/en-us/azure/bot-service/bot-service-quickstart?view=azure-bot-service-4.0)
- Subscription to Direct Line Channel on the MS Azure portal
- Your Azure Channel Secret Key
For Google DialogFlow Chatbots
- A configured Chatbot on the DialogFlow (https://console.dialogflow.com)
- GCP (Google Cloud Platform) and Service account and Keys
Connecting your BOT/Application to Syniverse Connector Service
The service will consist of two major parts - SCG MO Handler and API MT Handler.
· Creating a Connector in SCG
- Creating a MS Azure Connector
- Create a MS Azure connector (Request)
curl -X POST
https://api.syniverse.com/scg-external-api/api/v1/connect/connectors -H 'Cache-Control: no-cache' -H 'Content-Type: application/json' -H "Authorization: Bearer 8f8a41a5766eff1641a54e92tyi6f95" -d '{"type":"AZURE_BOT_DIRECT_LINE","sender_id":"Uu4txaiKbAWjMN8427QEM2","credentials":"ZrVkDm7_F24.cwA.BEs.Sz0w9A3HT1jhIo67glv8W4wz73y6J_Hd810FP6eFTpQ","external_id":"Test123"}'
Where:
- BOT type: AZURE_BOT_DIRECT_LINE
- Sender ID: Uu4txaiKbAWjMN8427QEM2 (SMS-Capable Sender ID)
- Credentials: Your MS Azure Bot Secret Key
- External ID: Optional unique identifier
Response
You will receive a <ConnectorID> as response to a successful request.
- Creating a DialogFlow Connector
To create a connector in the type field put “GOOGLE_DIALOG_FLOW” and in the credentials field put the content of the json file with the Dialogflow/GCP keys, properly escaped so can be put in JSON string. For example:
Please note that all quotes (") and all back slashes (\) in the key file content need to be escaped by a backslash, like this - \" or \\
Create a DialogFlow connector (Request)
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/connect/connectors \
-H 'Authorization: Bearer 3f233185-6357-3bd1-b286-14908d21f369' \
-H 'Content-Type: application/json' \
-d '{"type":"GOOGLE_DIALOG_FLOW","sender_id":"cEeua7AU15nWb8c2o8TjLo","credentials":"{ \"type\": \"service_account\", \"project_id\": \"kolanator-9600e\", \"private_key_id\": \"de59b6b44e99ae45068ac0892a7657d46904bbab\", \"private_key\": \"-----BEGIN PRIVATE KEY-----\\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDBPBzgaldPc9n7\\nUdakd+2xsY0L7zQsw6B/EcmpOGMBBCNSM7wsbluQZK806L5s/Tp0dy15r1nvAFBE\\nMjfjd3jerf5F4RlOf+idwvnE7SitkGASMV9LuwgTdnk0d3yGibchdSTcTpsvCGog\\njHlXghGH2yAUz2DZLcZEIebtYXi9Z45g4/mrQahVPdI6+MIMW7rcD90ZcM6sa6eH\\njoKEK52l8QGLVyLFSdLeVfX1xfuwjdAXlKpHuRPY7G8NdPjcIO9RB7zc73myvRge\\nAiPQZAFIQFMkfWkf5YezUfLh+0VNQb4n9PKbxJCnB+XLwq+odeg9NWD5ay1jtwou\\n8dtN4TjxAgMBAAECggEAFDXb1VL5/8rfrSwBlaEfgLrPxERIAjiRxEiRfXvyyuvq\\nX9IeZ81BEWiedJu1MwQHRaAjZvtCnj87pe5UrxtTToMHObrR4UZ6h2mZoxGk9AZK\\nLgzw6SROM27sPWMT6KRlvX+Zk9pkp7YrF21p0Y++kqWGBPctq3lgp8ad9wz/Slvo\\nOtJ9cRbSpIMMrxqRwZN2fg/wdzRNd/crRhvSGin+PIhafTQfAcHzHHvdE+EBUqjH\\nrr7uvtBawWaWXM6mwff07ThxLYMr+3ChLLoVe4UsBfV/QECT3wrz3WyP21KL3RrG\\nnVGAEwGguKc3Dk2Lg9XpR5BHg60ovRx7Dj9UcNF0qwKBgQDwiPB0kyPJl33JZ9uN\\n3Nj+wNt/Em5n5kNYsOBUSteM6MyNGwsQjomClHQNMrxyxqfrY4pamvqohOdERMMD\\nyqilpKW2fFeoQS9miviQclucCpmAPX7faqoZOHkiVZOd98L8bEG8oHHpidXGfme3\\n7ozH26vkTxIwzSTVqVZgqontxwKBgQDNqKRjjZC+N67sAVKKqKiVizaDhOYHhv9P\\nVRlSxO49kuYVVJ5NkF5kjV7o5vZxTcMSkLlEWWYNS7dX4qHzjRn9GpnYSrtHrqs7\\nPlK2nqN69CHDxGXkpSkY5vPhmh15XzgRaTtiezZtlop6rDb9bRuY/xYUX6CCv/G3\\nOv2owciDhwKBgQDVzRLWu9cKoFJZjKxWC6EByFESQULLrZvdINM1eZThFiiDoC8U\\nl23ZGLWS6a8h4jxt+XuID8uPsRqTzv78xs1i9tepPhr4XoCQiCRq2ItfRvisSX0V\\nf40Uf+MERsbAmfLCRkOkM4UtTawsFD2C+1I9b5/5fuMvZ5k/JZa2s7+IDwKBgQCG\\nqqFKVw6qoAe4nn0QMrSBh/EgWcvOrgVMS2sTmcRvKVvkJ86o95n3ueKmG2bQdpz/\\n8Sh/qxJ6LlRWBh8KPiEAbYTD7tuHasbROlQrJOHjxyy85kPaXpP0rHaSCbq3GTS7\\noe6y4/+V7veqsE4p0GI74vzwRlXyiAGde9FRyeKkzQKBgA0W1Itb5gMjdHTdPsx+\\nfeef/99hI8GISSHVc1npNgrsOIOlHsOt//zMRLHPtJarZ3mKzKkSz4+VqPLbmlK5\\nIMMvcBmH9O9UAcoxWCG6bBn9XZ9PsWjtDnR6DWgMoh67NaiQ/UMXOz25Bp/ludN/\\nHbD1q8SOJKUDyAZqCxAMMlt5\\n-----END PRIVATE KEY-----\\n\", \"client_email\" : \"kolanator-9854e@appspot.gserviceaccount.com\", \"client_id\": \"112680765748998725263\", \"auth_uri\": \"https://accounts.google.com/o/oauth2/auth\", \"token_uri\": \"https://oauth2.googleapis.com/token\", \"auth_provider_x509_cert_url\": \"https://www.googleapis.com/oauth2/v1/certs\", \"client_x509_cert_url\": \"https://www.googleapis.com/robot/v1/metadata/x509/kolanator-9600e@appspot.gserviceaccount.com\" }", "external_id":"my-df-to-rcs-connector"}'
Where:
- BOT type: GOOGLE_DIALOG_FLOW
- Sender ID: cEeua7AU15nWb8c2o8TjLo (RCS-Capable Sender ID)
- Credentials: Your GCP/Service account credentials
- External ID: Optional unique identifier
Response
You will receive a <ConnectorID> as response to a successful request.
Note that once your Sender ID has been configured for your Bot service, a MO Handler in the Sender ID properties will be changed to <SCG_CONNECT>. This means that all MO messages to the Sender ID will be forwarded to your BOT. It is therefore recommended that your Sender Address is dedicated to this service and not shared with any other application that is required to receive MO (Mobile Originated) messages
· Interacting with your Bot
- Send a MO (Mobile Originated) message to your Sender Address which will be passed to your BOT
- If your BOT responds, the messages will be delivered to the Mobile device
Other activities you can invoke on the connector service
· List a Connector
curl -X GET https://api.syniverse.com/scg-external-api/api/v1/connect/connectors/<ConnectorID > -H 'Cache-Control: no-cache' -H "Authorization: Bearer 8f8a41a5766eff1jk1a54e920d16f95"
· List all your Connectors
curl -X GET https://api.syniverse.com/scg-external-api/api/v1/connect/connectors -H 'Cache-Control: no-cache' -H "Authorization: Bearer 8f8a41a5766eff1641a54ji20d16f95"
· Update a Connector
curl -X POST https://api.syniverse.com/scg-external-api/api/v1/connect/connectors/<ConnectorID> -H 'Cache-Control: no-cache' -H 'Content-Type: application/json' -H "Authorization: Bearer 8f8a41a5766eff1641a54yu20d16f95" -d '{"sender_id":"my-updated-sender-id","credentials":"update-credentials","external_id":"changed-id-assigned-by-me","version_number":"1"}
· Delete a connector
curl -X DELETE https://api.syniverse.com/scg-external-api/api/v1/connect/connectors/<ConnectorID> -H 'Cache-Control: no-cache' -H "Authorization: Bearer 8f8a41a5766eff1641a54uj20d16f95"
For more information on the API endpoints for the Connector service, please visit our API reference page on the Developer community portal
FAQ
- Q: Does the connector service support BOT services hosted on Amazon Lex?
A: No. Please check back with us on future releases
- Q: How many messages per sec can the service support?
A: Default throughput for a connector service is 30 MPs.
- Q: Can I configure multiple sender IDs for my BOT service?
A: Yes, however a Sender ID can only be assigned to 1 Connector
- Q: How many connectors can I create
A: You can create as many connectors as you want. However, please note that each connector can only have one unique Sender ID.
0 Comments