Syniverse Chatbot Connector Service- Overview Guide

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
  • WhatsApp

 

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

For Google DialogFlow Chatbots

 

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

 

  1. Q: Does the connector service support BOT services hosted on Amazon Lex?

A: No. Please check back with us on future releases

  1. Q: How many messages per sec can the service support?

A: Default throughput for a connector service is 30 MPs.

  1. Q: Can I configure multiple sender IDs for my BOT service?

A: Yes, however a Sender ID can only be assigned to 1 Connector 

  1. 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.

 

 

 

 

 

 

Was this article helpful?
0 out of 0 found this helpful

0 Comments

Please sign in to leave a comment.