Skip to main content
Skip table of contents

How to assign traffic gradually

Overview

This document provides an in-depth exploration of gradual traffic assignment, a feature that allows an end-user to gradually assign traffic from one application to another. This can be particularly useful for testing, transitioning between applications, or handling special cases where staggered deployment is necessary. Gradual traffic assignment is supported for miniApps, flows, application tags, SND and PRD applications. Below, you will find detailed instructions on setting up and managing gradual traffic assignment effectively.

Authentication

Navigate to the API Authentication to learn more about Authorization Token Endpoint and Authentication process.

Error Codes

Omilia's HTTP response codes can be found on the HTTP Code Responses page.

API Reference

The following provides a thorough explanation of the gradual traffic assignment API endpoints.

Create a route to a new app

POST

{{baseUrl}}/api/numbers-routing

Creates a route to a new app to balance both apps.

This endpoint allows creating a gradual traffic assignment router. Once created, a phone number can be linked to two applications. Users can then specify weights (percentages of traffic) for each application, determining the likelihood of calls being routed to a particular application based on the assigned weights. These weights are set in the request body as described below.

Click to see the details

Headers

Content-type: application/json

Request Body

JSON
{
  "number": "string",
  "targetAppId": "string",
  "targetAppTag": "string",
  "step": 100,
  "initialWeight": 100,
  "isEnabled": true
}

Parameter

Type

Required

Description

number

String

Yes

A phone number.

targetAppId

String

Yes

The ID of the new application to attach the phone number to.

targetAppTag

String

No

The tag of the new application to attach the phone number to. It allows to distribute calls between several versions of the same application.

step

Integer

No

The number of the step. It increments the initialWeight of the source app.

Required values: 0-100.

initialWeight

Integer

No

Specifies the initial routing probability for the source application, which is the application to which the number was originally attached.

Required values: 0-100.

In case the initialWeight value is set up to 80, the source app will get 80% of the traffic and the target app will get 20%.

isEnabled

Boolean

No

Allows enabling and disabling routers at any time. When disabled, the source app only is mapped.

Response (Success)

CODE
HTTP/1.1 200 OK

Example

JSON
{
  "id": "string",
  "step": 0,
  "lastUpdateTime": "2024-06-07T11:15:19.610Z",
  "group": "string",
  "numbers": [
    "string"
  ],
  "appRoutes": [
    {
      "id": "string",
      "weight": 100,
      "appTag": "string",
      "order": 0,
      "appId": "string"
    },
     {
      "id": "string",
      "weight": 0,
      "appTag": "string",
      "order": 1,
      "appId": "string"
    }
  ],
  "active": true
}

Parameter

Type

Description

id

String

The ID of the application.

step

Integer

The number of the step. It increments the initialWeight of the source app.

lastUpdateTime

String

The time and date of the last update. The time is UTC.

Required format: YYYY-MM-DD HH:MM:SS:sss

group

String

The name of the group the application is assigned to.

numbers

Array of strings

List of phone numbers in the group.

appRoutes

Array of objects

List of applications to which the phone number has been attached.

id

String

The ID of the application.

weight

Integer

Specifies the routing probability for the application.

appTag

String

The application tag.

order

Integer

Identifies the source and target apps by indicating the sequence of routes:

  • 0 represents the source application.

  • 1 represents the target application.

When invoking the Get to the next step endpoint, the traffic weights transition incrementally from the app with the lower order (source) to the app with the higher order (target).

appId

String

The application ID number.

active

Boolean

Shows if the route is activated.

Get to the next step

POST

{{baseUrl}}/api/numbers-routing/number/{number}/next-step

Gets to the next step.

This endpoint allows to specify a step when creating a gradual deployment.

Click to see the details

Query Parameters

Parameter

Type

Required

Description

number

String

Yes

The number of the step. The initialWeight of the source app is incremented by the specified step. For example, if the initialWeight for the source app is 30 and the step is 20, by triggering this endpoint, the initialWeight will become 50.

In the future we are planning to introduce the scheduled step increase tool.

Response (Success)

CODE
HTTP/1.1 200 OK

Example

JSON
{
  "success": true,
  "message": "string"
}

Parameter

Type

Description

success

Boolean

The success status of the response.

message

String

Response message that contains the success status details

Update a router

PUT

{{baseUrl}}/api/numbers-routing

Updates the existing router by ID.

Click to see the details

Headers

Content-type: application/json

Request Body

JSON
{
  "id": "string",
  "targetAppId": "string",
  "targetAppTag": "string",
  "step": 100,
  "weight": 100,
  "isEnabled": true
}

Parameter

Type

Required

Description

id

String

Yes

The ID of the router to be updated.

targetAppId

String

No

The ID of the new application.

targetAppTag

String

No

The tag of the new application. It allows to distribute calls between several versions of the same application.

step

Integer

No

The number of the step. It increments the initialWeight of the source app.

Required values: 0-100.

initialWeight

Integer

No

Specifies the initial probability for the source application, which is the application to which the number was originally attached.

Required values: 0-100.

In case the initialWeight value is set up to 80, the source app will get 80% of the traffic and the target app will get 20%.

isEnabled

Boolean

No

Allows enabling and disabling routers at any time. When disabled, the source app only is mapped.

Response (Success)

CODE
HTTP/1.1 200 OK

Example

JSON
{
  "success": true,
  "message": "string"
}

Parameter

Type

Description

success

Boolean

The success status of the response.

message

String

Response message that contains the success status details

Get a router by ID

GET

{{baseUrl}}/api/numbers-routing/{id}

Retrieves a router by router ID.

Click to see the details

Query parameters

Parameter

Type

Required

Description

id

String

Yes

ID of the router.

Response (Success)

CODE
HTTP/1.1 200 OK

Example

JSON
{
  "id": "string",
  "step": 0,
  "lastUpdateTime": "2024-06-07T11:15:19.610Z",
  "group": "string",
  "numbers": [
    "string"
  ],
  "appRoutes": [
    {
      "id": "string",
      "weight": 100,
      "appTag": "string",
      "order": 0,
      "appId": "string"
    },
     {
      "id": "string",
      "weight": 0,
      "appTag": "string",
      "order": 1,
      "appId": "string"
    }
  ],
  "active": true
}

Find a detailed description of the response parameters.

Delete a router by ID

DELETE

{{baseUrl}}/api/numbers-routing/{id}

Deletes a router by ID.

Click to see the details

Query parameters

Parameter

Type

Required

Description

id

String

Yes

ID of the router.

Response (Success)

CODE
HTTP/1.1 200 OK

Example

JSON
{
  "success": true,
  "message": "string"
}

Parameter

Type

Description

success

Boolean

The success status of the response.

message

String

Response message that contains the success status details

Get a router by a phone number

GET

{{baseUrl}}/api/numbers-routing/number/{number}

Retrieves a router by a phone number.

Click to see the details

Query parameters

Parameter

Type

Required

Description

number

String

Yes

A phone number.

Response (Success)

CODE
HTTP/1.1 200 OK

Example

JSON
{
  "id": "string",
  "step": 0,
  "lastUpdateTime": "2024-06-07T11:15:19.610Z",
  "group": "string",
  "numbers": [
    "string"
  ],
  "appRoutes": [
    {
      "id": "string",
      "weight": 100,
      "appTag": "string",
      "order": 0,
      "appId": "string"
    },
     {
      "id": "string",
      "weight": 0,
      "appTag": "string",
      "order": 1,
      "appId": "string"
    }
  ],
  "active": true
}

Find a detailed description of the response parameters.

Get routers for the current user

GET

{{baseUrl}}/api/numbers-routing

Retrieves all routers for the current user.

Click to see the details

Query Parameters

Parameter

Type

Required

Description

isInProgress

Boolean

No

Default value: False.

Response (Success)

CODE
HTTP/1.1 200 OK

Example

JSON
{
  "id": "string",
  "step": 0,
  "lastUpdateTime": "2024-06-07T11:15:19.610Z",
  "group": "string",
  "numbers": [
    "string"
  ],
  "appRoutes": [
    {
      "id": "string",
      "weight": 100,
      "appTag": "string",
      "order": 0,
      "appId": "string"
    },
     {
      "id": "string",
      "weight": 0,
      "appTag": "string",
      "order": 1,
      "appId": "string"
    }
  ],
  "active": true
}

Find a detailed description of the response parameters.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.