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 exceptional 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 how to set up and manage gradual traffic assignments effectively.

Authentication

Navigate to the API Authentication to learn more about the 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 router for a new application

POST	{{baseUrl}}/api/numbers-routing	Creates a router to balance call traffic between two applications gradually.

This endpoint allows the creation of a gradual traffic assignment router. When the endpoint is called, a router is created with two routes: one for the source application (the application to which the phone number is currently attached) and one for the target application. Once created, a phone number is linked to both applications. Traffic is then assigned based on parameters that control a gradual transition using a defined step, determining the likelihood of calls being routed to each application.

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 value of the step that increments `weight` 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 initially attached. Required values: 0-100. If the `initialWeight` value is set to 80, the source app will receive 80% of the traffic, and the target app will receive 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 value of the step that increments `weight` 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 to which the application is assigned.
`numbers`		Array of strings	List of phone numbers in the group.
`appRoutes`		Array of objects	A 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.

Complete routing

POST	{{baseUrl}}/api/numbers-routing/{id}/complete	Completes the routing (deployment).

This endpoint completes the routing by setting the number’s application to the router’s target application and then deleting the router.

Click to see the details

Query Parameters

Parameter	Type	Required	Description
`id`	String	Yes	The router’s ID that will be completed

Response (Success)

JSON

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 to the next step

POST	{{baseUrl}}/api/numbers-routing/number/{number}/next-step	Gets to the next step.

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

Click to see the details

Query Parameters

Parameter	Type	Required	Description
`number`	String	Yes	The phone number to which the router the step increment will be applied. The source app’s `weight` is incremented by the specified step value. 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 plan 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 value of the step that increments `weight` 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 initially attached. Required values: 0-100. If the `initialWeight` value is set to 80, the source app will receive 80% of the traffic, and the target app will receive 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.