Omni-Channel Messaging
Documentation /

Communication Assistant

SCG Communication Assistant Application

Overview

The SCG Communication Assistant Application allow enterprises to define application behavior using a XML script. The Communication Assistant application offers a simple yet powerful way for Enterprise to quickly develop solutions without having to build their application to call all applicable SCG API resources required for that particular solution. For example, to provide an easy yet powerful way for Businesses to quickly add a secure verification solution to their applications, Syniverse has developed a voice-based solution powered by SCG Communication assistant IVR application that integrates passcode gathering (digit collection) and Text-to speech voice call for user passcode verification purposes as one of the possession factor in a multi-factor authentication soluution. The customizable application script is associated with a Sender address. SCG Communication Assistant will then use the Application Script to handle incoming calls and messages as required by the solution.

Prerequisite

Prerequisite for using the SCG Communication Assistant Application are:

  1. A Syniverse Developer Community account
  2. A syniverse application ( for your auth keys)
  3. Subscription to Voice and Messaging Service offering
  4. Events Manager subscription
  5. A private sender address (E.164 formatted Longcode telephone number) with the appropriate Voice capability provisioned by Syniverse

Key Features

  1. Customizable XML scripting template for IVR solutions
  2. Support for Toll-free and Telephone number sender addresses
  3. Multi-language Text-to Speech conversion
  4. pre-defined call recording and playback
  5. Digit collectors
  6. Event Notification manager for callback/webhooks
  7. External API hooks ( e.g. credit-card processing )

Key Use Cases

  1. Auto Attendants- Manage inbound calls (Must have Inbound calling enabled and provisioned)
  2. Voice based Token verification/2FA
  3. Customer surveys/feedback
  4. Payment processing/Bill payment
  5. Marketing Campaigns

 

API Resources

Application Scripts:

  • Actions and triggers can be defined in the application scripts
  • Steps are defined in Application scripts
  • Each step has a prompt and choices.
  • DTMF digits (digit collections) can be collected after each prompt which triggers advancement to corresponding step or other actions.

Prompts:

  • Prompts can be text, file, audio file, or URL to audio file.

Actions:

  • Can advance to another step.
  • Can make a purchase
  • Can call an external API
  • Can trigger a voice call transfer - Please note that this functionality is only available with US Voice Sender IDs. Additional provisioning is required.
  • Can trigger an event with Inbound DTMF digit payload (e.g. enter PIN/passcode).
  • Can pause IVR flow waiting for external application input.

Create a XML-Script

{baseURL}/scg-external-api/v1/api/communication_applications/applications/scripts:

  • Script_id
  • Script_name
  • Script_description
  • Script_capabilities - Voice
  • Script_body Escaped JSON

Create an Instance

{baseURL}/scg-external-api/v1/api/assistant/communication_applications/instances

  • communication_application_id
  • communication_application_name
  • communication_application_description
  • instance_id
  • script_id
  • sender_id
  • state - Enabled, Disabled

Start a Session

{baseURL}/scg-external-api/v1/api/assistant/communication_applications/instances/{instance_id}/sessions

  • to-address
  • external_id
  • current_step_id
  • state - Active, Paused

Process a result of the Session

{baseURL}/scg-external-api/v1/api/assistant/communication_applications/instances/{instance_id}/sessions/{session_id}/processor_results

  • processor_id
  • next_step_id
  • prompt_data

Event Notifications

Communication_Application_Session_Complete
  • Communication_application_id
  • Sender_id
  • to_address
  • from_address
  • result code
  • result_details
  • invocation_timestamp
Communication_Application_Session_custom_event
  • Communication_application_id
  • custom_data
Communication_Application_processor
  • session_id
  • processor_id
  • user_data

For more information on how to setup and subscribe to the event notification service, please see the Webhook guide

Example Use Cases - IVR Verification

Solution Use case

  1. Customer generated token or Syniverse customizable token generation, user validation and verification (Optional)
  2. Verification of generated token via dtmf( digit collector ) or Voice confirmation using outbound calling
  3. Verification/Validation confirmation events posted to business application

Benefits of a Voice-based Verification solution

  1. Cost effective and easy to use application, saving time-to market & development time
  2. Voice-based IVR solution with support for mobile or landline calling
  3. Customizable XML script and call recording template for outbound call or text to speech

Solution setup guide:

There are a few options when considering using the Programmable Voice Solution, we recommend talking to a Syniverse expert to assist you with choosing the best option for your application.

What you will need:

  • A SDC (Syniverse Developer Community) account
  • Subscription to a Voice Calling API service offering from the SDC portal
  • Solution option ( A Syniverse sales expert can assist you with option, terms and pricing)
  • Necessary skill to create a XML script ( See sample below)

How it works

Step1 : Create your verification script

curl -X \
POST "https://api.syniverse.com/scg-external-api/api/v1/assistant/communication_applications/applications/scripts" \
-H 'Authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{ 
"name":"IVR_Test", 
"description":"IVR script test PIN validation", 
"body":"<?xml version=\"1.0\" encoding=\"UTF-8\"?><ivr id=\"2\" description=\"IVR demo flow 5067\" voice=\"susan\" initialStep=\"welcome\" interDigitTimeout=\"15\" maxDigits=\"1\" maxConsecutiveIterations=\"3\"> <step name=\"welcome\" type=\"gather\" prompt=\"Hello. This is a message from the Syniverse. Press one to continue\"> <choice digit=\"1\" next=\"pinValidation\" /> <choice next=\"pinValidation\"/> </step> <step name=\"pinValidation\" type=\"gather\" voice=\"susan\" prompt=\"Please enter the Pin that is shown on your Screen.\" maxDigits=\"6\" minDigits=\"1\" maxConsecutiveIterations=\"3\" interDigitTimeout=\"10\"> <choice next=\"processValidation\"/> </step> <step name=\"processValidation\" type=\"announce\" voice=\"susan\" prompt=\"Validating Pin. Please kindly wait\"> <processor id=\"pinValidation\" event=\"processor_event:processor_id={id};digits={digits};session_id={session};call_id={callId}\"> <timeout seconds=\"120\" next=\"invalidPin\"/> </processor> </step> <step name=\"postValidationSuccess\" type=\"announce\" voice=\"susan\" prompt=\"The Pin has been validated Successfully.\"> <choice next=\"hangup\"/> </step> <step name=\"invalidPin\" type=\"gather\" voice=\"susan\" prompt=\"The pin that was entered is incorrect. Press 1 to re-enter the pin.\"> <choice next=\"pinReValidation\" digit=\"1\" maxDigits=\"1\"/> <choice next=\"hangup\"/> </step> <step name=\"pinReValidation\" type=\"gather\" voice=\"susan\" prompt=\"Please enter the Pin that is shown on your screen.\" maxDigits=\"6\" maxConsecutiveIterations=\"1\"> <choice next=\"processValidation\"/> </step> <step name=\"hangup\" type=\"hangup\"voice=\"susan\" prompt=\"Goodbye and Have a nice day\"/></ivr>"
}'

Please note that once you create script, you can use the same script ID repeatedly till you need to change your flow.

 

Step 2: Create an Instance using the scriptID

curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/assistant/communication_applications/instances \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"sender_id":"il4eAFkYQiRcCesfDHyIQ",  <----  Voice capable Sender ID
"script_id":"3PBalxNKF4PFGmggLYWqp2",  <----  Script ID from step 1
"allow_incoming_call": false,
"state":"ENABLED"

}'

Response:{"BnwSgTjld4FwrdlUJEudw6"} -  This is the Instance ID

Please note that once you create an instance, you can use the same instance ID repeatedly till you need to change your flow.

 

Step 3: Start an IVR Session using the InstanceID

curl -X POST https://api.syniverse.com/scg-external-api/api/v1/assistant/communication_applications/instances/BnwSgTjld4FwrdlUJEudw6/sessions 
-H 'authorization: Bearer {token}' -H 'content-type: application/json' 
-d '{"to_address":"+14085551212","state":"ACTIVE", "external_id":"123456236"}'

Response: {"2u1iMIDwmTam9WOVWNfLw"} - This is the Session ID

 

Step 4 : Gather Event for the Session

An event for the session is posted to your application via your webhook with details you will need to provide a result/response to your customer

{
  "topic": "SCG-Communication-Assistant",
  "attempt": 1,
  "event": {
    "fld-val-list": {
      "communication_application_id": "100",
      "company-id": 1511000,
      "processor_id": "pinValidation",
      "user_data": "processor_event:processor_id=pinValidation;digits=85471239;session_id=2u1iMIDwmTam9WOVWNfLw;call_id=UATL0iDGdwPmyjnITR4Ez7?&instance=9Q8Sw62YWbTcp91gUXhLI3",
      "application_id": 17563
    },
    "evt-tp": "communication_application_processor",
    "timestamp": "2021-03-25T17:33:51.064Z"
  },
  "event-id": "sfECO2reQ5KDxjBTcQmfgQ"
}

 

Step 5: Post processor Event to IVR

 Provide a successful response to your customer using the details from the events. This request will send a response to the user and end the call.

curl -L -X POST 'https://api.syniverse.com/scg-external-api/api/v1/assistant/communication_applications/instances/9Q8Sw62YWbTcp91gUXhLI3/sessions/2u1iMIDwmTam9WOVWNfLw/processor_results'
-H 'authorization: Bearer{token}' -H 'content-type: application/json' 
--data-raw 
'{
"call_id":"UATL0iDGdwPmyjnITR4Ez7", <----- caller ID 
"processor_id":"pinValidation",
"next_step":"postValidationSuccess",
"prompt":"Thank you, your passcode has been authenticated"
}'

 

 

Copyright © 2023 Syniverse Technologies