Reference Turnkey Applications Tutorials Visual Designer
    • REST API
      • Overview
      • API Endpoint
      • Authentication
      • Requests
      • Responses
      • Paging
      • Reason Codes Dictionary
    • Management APIs
      • Accounts
      • Identity Access Management Early Access
        • Identity Access Management Overview
        • Identity Access Management API
          • User Management
            • Create a User
            • Update a User
            • Retrieve a User
            • Delete a User
          • API Keys Management
            • Create an API Key
            • Update an API Key
            • Retrieve an API Key
            • Delete an API Key
      • Applications
      • Clients
        • Create a Client
        • Delete a Client
        • Change Client’s Password
        • Get a List of Available Clients
      • Incoming Phone Numbers
        • IncomingPhoneNumber Instance Resource
        • IncomingPhoneNumbers List Resource
        • Local IncomingPhoneNumber Factory Resource
        • Toll-Free IncomingPhoneNumber Factory Resource
        • Mobile IncomingPhoneNumber Factory Resource
        • Attach a phone number to an application
        • Delete a phone number
        • List of Phone Numbers
        • Incoming Phone Number Regex Support
      • Notifications
      • Usage Records
    • Voice
      • Calls
        • Call List Resource URI
        • Making a Call
        • Modifying Live Calls
        • Examples
        • List Filter
        • Paging Information
      • Conference Management
        • Supported Operations
        • Conference List Resource URI
      • Conference Participants Management
        • Participants List Resource URI
      • Gather DTMF
      • Gather Speech
      • Say
      • Play
      • Hold
      • Recordings
      • Refers
        • Resource Properties
        • Supported Operations
        • Paging Information
      • Resume
      • SIP Refer Support
    • SMS
      • Messages
        • Send SMS
        • Get SMS List
        • Get single SMS Information
        • SMS Attributes
      • Email
    • RCML
      • Overview
        • Interacting with Your Application
        • RCML Verbs
      • Dial
        • Client
        • Conference
        • Number
        • SIP
      • Email
      • Gather
      • Say
      • Play
      • SMS
      • Hold
      • Resume
      • Hangup
      • Pause
      • Redirect
      • Record
      • Reject
      • Refer
    • Visual Designer API
      • List Application Templates
      • :List a Specific Application Template
      • Create a Visual Designer Application
      • Get Application Details
      • Save Application Changes
      • Create Application Parameters
      • List Application Parameters
      • Delete Application Parameters
      • Upload Application Media Files
      • List Application Media Files
      • Play Application Media Files
      • Delete Application Media Files
      • Get Application Logs
      • Delete Application Logs
      • Get Application Settings
      • Modify Application Settings
      • Rename an Application
      • Delete an Application
      • Get Visual Designer Configuration
    • Turnkey Apps APIs
      • Smart 2FA
        • Sending One-Time Passwords
        • Verifying One-Time Passwords
        • Cancel One-Time Passwords
        • Session Detail Record (SDR)
        • Get list of One-Time Passwords
        • Get a Single One-Time Password
        • Usage Record One-Time Passwords
        • Common Response Error Code
        • Limit
          • Create Limit
          • Update Limit
          • Delete Limit
          • Get List of Limits
      • Call Queuing
      • Auto Attendant
        • Users
        • Announcement
        • Auto Attendant System
        • Menu
        • Schedule
        • Phone Number
        • Usage Records
        • Third Party Integration
      • Number Masking
        • Application
        • Mask Number Pool
        • Context
        • Participants
        • Interactions
        • Usage Records
      • Task Router
docs 1.0
  • docs
    • 1.0
  • docs
  • Accessing HTTP resources with External Service element

Accessing HTTP resources with External Service element

CPaaS Visual Designer’s External Service element is a tool for making HTTP requests to external services and processessing their responses. This document focuses on the former. It explains its capabilities and describes how it can be used from Visual Designer’s UI. Currently ES client supports:

  • GET or POST request methods

  • JSON or web form content types

  • HTTP or HTTPS schemes

  • basic HTTP authentication

A Simple GET request

Here is a simple GET request with parameters:

Selection_069

By default, all requests use GET method. Note that name-value parameter is user defined. Such parameters are appended in the query when the request is made. It’s a good practice to keep parameters in their own fields and avoid putting them directly in the Service Url field. Here is what the actual data on the wire:

Request

GET /services/simpleGetRequest.php?name=foo HTTP/1.1

Host: localhost

Response

HTTP/1.1 200 OK

A note on Variable expansion

Both Service Url and Value fields support variable expansion. That means that all $variables and references in them will be replaced by their actual value before the request is being made.

For example:

Selection_071

Here $firstname variable will be expanded to its actual content.

$firstname → name

POSTing web forms

Here is a simple POST request:

post request

In order to access the advances features of the ES client you will need to click on the gear icon. Also notice the following:

  • You can switch the HTTP method used by using the Method drop down menu. Default is GET.

  • Either www form or json content types are supported. For common url-encoded request use www form.

  • Manually building the body of the request with ‘&’ and ‘=’ can often be a daunting and error-prone task. Check Automatically populate from service parameters to let Visual Designer build the request body from the Name/Value pairs you have defined.

Let’s see it in action:

Request

POST /services/simplePostRequest.php HTTP/1.1

Content-Length: 21

Content-Type: application/x-www-form-urlencoded

…​

name=foo&lastname=bar

Response

HTTP/1.1 200 OK

Provide POST body manually

You can also provide the POST body manually if you want. For example:

provide POST body manually

Notice how we have removed the service parameters and provided the url-encoded body instead. In case the service parameters were still there, they would be ignored.

POSTing JSON

Using a JSON request body is not much different:

Selection_075

POSTing JSON can only be done by manually providing the JSON expression. You will just need to set the Content type to json and type the JSON expression.

Here is an example of JSON expression:

{"name":"$firstname","lastname":"bar"}

Note that double quotes are being used in the JSON expression. Visual Designer does not know about the json syntax and its types. It will just go for a search‘n’replace. You will need to make sure that a valid json expression will result at the end.

IP Address Whitelisting

Visual Designer makes HTTP requests to your server to fetch your business logic instructions. Some users prefer to know which IP address the request from CPaaS is coming from in order to open up specific ports in a firewall. However, due to the fluid nature of our cloud architecture, we don’t have a set range of IPs that requests are sent from or know in advance what they will be so please use proper security credentials & authentication when using CPaaS Visual Designer External Service by following the steps in the below section.

Using basic HTTP authentication

For services that are protected with basic http authentication the user credentials need also to be provided:

Selection_076

Handling service HTTP errors

In case the external service fails with an HTTP error code a handler can be used. In order to set up the handler you will need to:

  1. create a handler Visual Designer module

  2. bind the ES component to this handler using ‘On Remote Error’ drop down menu

Here is a sample handler module labeled ‘Error announcement’:

Selection_077

You can find the ‘On Remote Error’ drop down menu at the bottom of the ES component. Here is how it should look like after binding it to the handler module:

Selection_078
Platform

Programmable Voice

Programmable SMS

Turnkey Applications

Smart 2FA

Call Queue

Auto Attendant

Number Masking

Task Router

Campaign Manager

Learn

Terms And Conditions

About

ABOUT

CONTACT US

© 2020, All rights reserved.