VoxEngine Development

Working with API requests

Learn how to make and accept HTTP requests and send emails in your Voximplant scenarios.
View as Markdown

VoxEngine facilitates communication between our cloud and third-party services or APIs through the Net namespace. Additionally, it provides guidance on creating and handling HTTP requests, as well as sending emails, within your JavaScript cloud scenarios.

HTTP API requests

Two methods that allow performing requests: httpRequest and httpRequestAsync.

The httpRequest method performs synchronous HTTP requests. Its second parameter is a callback function that can accept the HttpRequestResult object and process the object’s properties.

Synchronous request
1Net.httpRequest(
2  'https://voximplant.com/',
3  function (e) {
4    if (e.code == 200) {
5      Logger.write('Connected successfully');
6      Logger.write('code:  ' + e.code);
7      Logger.write('data:  ' + e.data);
8      Logger.write('error:  ' + e.error);
9      Logger.write('headers:  ' + JSON.stringify(e.headers));
10      Logger.write('raw_headers:  ' + e.raw_headers);
11      Logger.write('text:  ' + e.text);
12    } else {
13      Logger.write('Unable to connect');
14    }
15  },
16  { rawOutput: true }
17);

The httpRequestAsync method performs asynchronous HTTP requests, i.e., the method returns a Promise that resolves with the HttpRequestResult object.

Asynchronous request
1Net.httpRequestAsync('https://voximplant.com/').then(function () {
2  Logger.write('request complete');
3});
Timeouts and default verb

By default, both methods use the GET verb to perform requests. TCP connect timeout is 6 seconds, and total request timeout is 90 seconds.

WebSocket connections

In addition to HTTP API requests, VoxEngine allows developers to use the WebSocket protocol for two-way communication.

To send data via the WebSocket protocol:

  1. Require the Modules.WebSocket module in your scenario
  2. Create a WebSocket connection via the VoxEngine.createWebSocket method
  3. Use the webSocket.send method to send text data into the connection
  4. Subscribe to WebSocketEvents, such as MESSAGE, to process the replies.

Here is an example of sending text data to a WebSocket connection:

Sending text via WebSockets
1require(Modules.WebSocket);
2
3VoxEngine.addEventListener(AppEvents.CallAlerting, ({ call }) => {
4  call.answer();
5  call.addEventListener(CallEvents.Disconnected, VoxEngine.terminate);
6
7  const webSocket = VoxEngine.createWebSocket('wss://your-url.example.com');
8
9  webSocket.addEventListener(WebSocketEvents.OPEN, () => {
10    Logger.write('Sending message');
11    webSocket.send('Some test message');
12  });
13  webSocket.addEventListener(WebSocketEvents.MESSAGE, (message) => {
14    Logger.write(`Received message ${message.text}`);
15  });
16  webSocket.addEventListener(WebSocketEvents.CLOSE, () => {
17    VoxEngine.terminate();
18  });
19});

You can find more information about uning the WebSocket protocol with VoxEngine scenarios in the Sending media over WebSockets article.

Sending emails

Sometimes it is convenient or even necessary to send emails to an external service. To do that, you can use either the sendMail or sendMailAsync methods. Both of them process the SendMailResult object after a successful call.

Synchronous email
1Net.sendMail(
2  'smtp.server.com',
3  'from@server.com',
4  'to@server.com',
5  'Title of the letter',
6  'Body of the letter',
7  function stub() {},
8  { login: 'login_from@server.com', password: 'password_from@server.com' }
9);

For asynchronous sending, use this:

Asynchronous email
1sendMailAsync(mailServerAddress: String, from: String, to: String|Array, title: String, body: String, options: Net.SendMailOptions): Promise