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)
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: 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)
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)
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)
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)
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)
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)
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.