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.

{{baseUrl}} depends on the user's environment which could be the following:

EU1 - https://eu1-m.ocp.ai/integrations

US1 - https://us1-m.ocp.ai/integrations

US2 - https://us2-m.ocp.ai/integrations

US1W - https://us1-w-m.ocp.ai/integrations

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.