Channel Manager API

The Channel Manager API provides a way of managing configuration and data related to various messaging channels in the Vonage Messages API. Find out more at https://developer.vonage.com/en/api/channel-manager.

Download OpenAPI Specification

WhatsApp WABAs

API endpoints relating to working with WhatsApp Business Accounts (WABAs)

Available Operations

List WhatsApp Business Accounts (WABAs)

List all WhatsApp Business Accounts (WABAs) that are associated with the Vonage account.

gethttps://api.nexmo.com/v1/channel-manager/whatsapp/wabas

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Query Parameters

page

integer

Min1

Default1

example1

Page number to retrieve

page_size

integer

Min1

Default10

example20

Number of items to return per page

order

string

The order.

Must be one of:ascdesc

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

page_size

integer

Min1

Default10

example20

The size of the page

page

integer

Min1

Default1

example1

The current page

total_pages

integer

Min1

example42

Total number of pages

total_items

integer

example871

The total number of items in the resource list

_embedded

object

wabas

array

waba_id

string

Required

example345688589250625

The ID of the WhatsApp Business Account.

api_key

string

Required

exampleabc123

The API key of the Vonage account associated with the WhatsApp Business Account.

name

string

Required

exampleMy Business

The name of the WhatsApp Business Account.

account_review_status

string

Required

exampleApproved

The review status of the WhatsApp Business Account.

Must be one of:PendingApprovedRejected

timezone_id

string

Required

example58

The ID of the timezone of the WhatsApp Business Account.

currency

string

Required

exampleUSD

The currency of the WhatsApp Business Account.

solution_id

string

example1234567890

The ID of the solution of the WhatsApp Business Account. Applies for WABAs onboarded through a partner solution

country

string

exampleUS

The country of the WhatsApp Business Account's owning Meta Business account.

business_id

string

example224654643345

ID of the business manager or portfolio that contains the WhatsApp Business Account

business_name

string

exampleVonage Communication APIs & Conversational Commerce Platform

Name of the business manager or portfolio that contains the WhatsApp Business Account

status

string

DefaultACTIVE

exampleACTIVE

WhatsApp Business Account status

Must be one of:ACTIVEINELIGIBLENOT_STARTEDINELIGBLE_ON_BEHALF_OF_WABAPENDINGDELETEDMIGRATEDBANNEDRESTRICTEDRATE_LIMITEDFLAGGEDCONNECTEDDISCONNECTEDUNKNOWNUNVERIFIEDOFFLINE

whatsapp_business_manager_messaging_limit

string

exampleTIER_10K

Maximum number of unique WhatsApp user phone numbers that your Business Manager account can message, outside of a customer service window, within a moving 24-hour period. This limit is shared across all WhatsApp phone numbers owned by your business.

For more information on messaging limits see the Meta documentation.

Must be one of:TIER_100KTIER_10KTIER_250TIER_2KTIER_UNLIMITEDUNTIERED

marketing_messages_onboarding_status

string

exampleELIGIBLE

Onboarding status of the WhatsApp Business account into Marketing Messages API.

Must be one of:INELIGIBLE_ON_BEHALF_OF_WABAINELIGIBLE_INACTIVE_OR_RESTRICTEDINELIGIBLE_COUNTRY_NOT_SUPPORTEDINELIGIBLE_USING_WHATSAPP_BUSINESS_APPELIGIBLEPENDING_VALID_PAYMENT_METHODPENDING_INTERNAL_SETUPONBOARDED

_links

object

HAL links for page-based paginated collections

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

first

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

object

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

object

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

last

object

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

Get a specific WhatsApp Business Account (WABA)

Retreive details of a specific WhatsApp Business Account (WABA).

gethttps://api.nexmo.com/v1/channel-manager/whatsapp/wabas/:waba_id

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

waba_id

string

Required

example345688589250625

The waba_id of the WhatsApp Business Account (WABA).

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

waba_id

string

Required

example345688589250625

The ID of the WhatsApp Business Account.

api_key

string

Required

exampleabc123

The API key of the Vonage account associated with the WhatsApp Business Account.

name

string

Required

exampleMy Business

The name of the WhatsApp Business Account.

account_review_status

string

Required

exampleApproved

The review status of the WhatsApp Business Account.

Must be one of:PendingApprovedRejected

timezone_id

string

Required

example58

The ID of the timezone of the WhatsApp Business Account.

currency

string

Required

exampleUSD

The currency of the WhatsApp Business Account.

solution_id

string

example1234567890

The ID of the solution of the WhatsApp Business Account. Applies for WABAs onboarded through a partner solution

country

string

exampleUS

The country of the WhatsApp Business Account's owning Meta Business account.

business_id

string

example224654643345

ID of the business manager or portfolio that contains the WhatsApp Business Account

business_name

string

exampleVonage Communication APIs & Conversational Commerce Platform

Name of the business manager or portfolio that contains the WhatsApp Business Account

status

string

DefaultACTIVE

exampleACTIVE

WhatsApp Business Account status

Must be one of:ACTIVEINELIGIBLENOT_STARTEDINELIGBLE_ON_BEHALF_OF_WABAPENDINGDELETEDMIGRATEDBANNEDRESTRICTEDRATE_LIMITEDFLAGGEDCONNECTEDDISCONNECTEDUNKNOWNUNVERIFIEDOFFLINE

whatsapp_business_manager_messaging_limit

string

exampleTIER_10K

For more information on messaging limits see the Meta documentation.

Must be one of:TIER_100KTIER_10KTIER_250TIER_2KTIER_UNLIMITEDUNTIERED

marketing_messages_onboarding_status

string

exampleELIGIBLE

Onboarding status of the WhatsApp Business account into Marketing Messages API.

_links

object

self

object

Link to the current resource (always required in HAL)

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

numbers

object

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

List Numbers for a WhatsApp Business Account (WABA)

List all Numbers associated with a WhatsApp Business Account (WABA).

gethttps://api.nexmo.com/v1/channel-manager/whatsapp/wabas/:waba_id/numbers

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

waba_id

string

Required

example345688589250625

The waba_id of the WhatsApp Business Account (WABA).

Query Parameters

page

integer

Min1

Default1

example1

Page number to retrieve

page_size

integer

Min1

Default10

example20

Number of items to return per page

order

string

The order.

Must be one of:ascdesc

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

page_size

integer

Min1

Default10

example20

The size of the page

page

integer

Min1

Default1

example1

The current page

total_pages

integer

Min1

example42

Total number of pages

total_items

integer

example871

The total number of items in the resource list

_embedded

object

wabas

array

phone_number

string(e164)

Required

example447451277751

The phone number associated with the WhatsApp Business Account.

number_id

string

Required

example293464193855848

The ID of the phone number associated with the WhatsApp Business Account.

waba_id

string

Required

example345688589250625

The ID of the WhatsApp Business Account.

api_key

string

Required

exampleabc123

The API key of the Vonage account associated with the WhatsApp Business Account.

verified_name

string

exampleMy Business

The WhatsApp display name for number

code_verification_status

string

exampleVERIFIED

Indicates the phone number's one-time password (OTP) verification status.

Only phone numbers with a VERIFIED status can be registered.
An EXPIRED status means that the phone number was previously verified but the 14 day verification period has ended. If the phone number is not registered, it will need to be verified again.

Must be one of:NOT_VERIFIEDVERIFIEDEXPIRED

display_phone_number

string

example+447451277751

How the number is displayed on WhatsApp accounts.

messaging_limit_tier

string

exampleTIER_100K

The messaging limit tier of the phone number. See WhatsApp messaging limits

Must be one of:TIER_50TIER_250TIER_1KTIER_10KTIER_100KTIER_UNLIMITED

quality_score

object

The quality score of the phone number. See WhatsApp Business phone number’s quality rating

score

string

exampleGREEN

The quality score of the phone number.

GREEN: High quality
YELLOW: Medium quality
RED: Low quality

Must be one of:GREENYELLOWRED

throughput

object

The throughput level of the phone number. Indication of throughput permissible by WhatsApp e.g. STANDARD is the default 80 messages/sec

level

string

exampleSTANDARD

The throughput rate of the phone number.

_links

object

HAL links for page-based paginated collections

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

first

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

object

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

object

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

last

object

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

Get a specific WhatsApp Business Account (WABA) Number

Retreive details of a specific Number associated with a WhatsApp Business Account (WABA).

gethttps://api.nexmo.com/v1/channel-manager/whatsapp/wabas/:waba_id/numbers/:whatsapp_number

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

waba_id

string

Required

example345688589250625

The waba_id of the WhatsApp Business Account (WABA).

whatsapp_number

string(e164)

Required

example447451277751

The WhatsApp number.

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

phone_number

string(e164)

Required

example447451277751

The phone number associated with the WhatsApp Business Account.

number_id

string

Required

example293464193855848

The ID of the phone number associated with the WhatsApp Business Account.

waba_id

string

Required

example345688589250625

The ID of the WhatsApp Business Account.

api_key

string

Required

exampleabc123

The API key of the Vonage account associated with the WhatsApp Business Account.

verified_name

string

exampleMy Business

The WhatsApp display name for number

code_verification_status

string

exampleVERIFIED

Indicates the phone number's one-time password (OTP) verification status.

Only phone numbers with a VERIFIED status can be registered.
An EXPIRED status means that the phone number was previously verified but the 14 day verification period has ended. If the phone number is not registered, it will need to be verified again.

Must be one of:NOT_VERIFIEDVERIFIEDEXPIRED

display_phone_number

string

example+447451277751

How the number is displayed on WhatsApp accounts.

messaging_limit_tier

string

exampleTIER_100K

The messaging limit tier of the phone number. See WhatsApp messaging limits

Must be one of:TIER_50TIER_250TIER_1KTIER_10KTIER_100KTIER_UNLIMITED

quality_score

object

The quality score of the phone number. See WhatsApp Business phone number’s quality rating

score

string

exampleGREEN

The quality score of the phone number.

GREEN: High quality
YELLOW: Medium quality
RED: Low quality

Must be one of:GREENYELLOWRED

throughput

object

The throughput level of the phone number. Indication of throughput permissible by WhatsApp e.g. STANDARD is the default 80 messages/sec

level

string

exampleSTANDARD

The throughput rate of the phone number.

_links

object

self

object

Link to the current resource (always required in HAL)

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

Get the profile for a specific WhatsApp Business Account (WABA) Number

Retreive details of the profile for a specific Number associated with a WhatsApp Business Account (WABA).

gethttps://api.nexmo.com/v1/channel-manager/whatsapp/numbers/:whatsapp_number/profile

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

whatsapp_number

string(e164)

Required

example447451277751

The WhatsApp number.

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

about

string

exampleAbout my business

Information about the profile

address

string

example123 Main Street, Anytown, USA

The address of the profile

description

string

exampleDescription of my business

The description of the profile

string

examplebob@example.com

The email address of the profile

profile_picture_url

string(uri)

examplehttps://example.com/profile.png

URL of picture for the profile. Profile picture must be a square JPG or PNG, with min dimensions of 192px x 192px, and max dimensions of 640 px x 640 px, and a max file size of 800 kb. If the image is larger, it will get automatically centre-cropped to fit these dimensions

websites

array

URLs of websites for the profile

vertical

string

exampleOTHER

The Industry or Business Category of the WhatsApp Profile

Must be one of:APPARELAUTOBEAUTYEDUENTERTAINEVENT_PLANFINANCEGOVTGROCERYHEALTHHOTELNONPROFITOTHERPROF_SERVICESRESTAURANTRETAILTRAVEL

messaging_product

string

examplewhatsapp

The messaging product with which the profile is associated.

Must be one of:whatsapp

_links

object

self

object

Link to the current resource (always required in HAL)

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

Update the profile for a specific WhatsApp Business Account (WABA) Number

Update details of the profile for a specific Number associated with a WhatsApp Business Account (WABA).

patchhttps://api.nexmo.com/v1/channel-manager/whatsapp/numbers/:whatsapp_number/profile

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

whatsapp_number

string(e164)

Required

example447451277751

The WhatsApp number.

Request Body
Content Type
application/json

about

string

exampleAbout my business

Information about the profile

address

string

example123 Main Street, Anytown, USA

The address of the profile

description

string

exampleDescription of my business

The description of the profile

string

examplebob@example.com

The email address of the profile

profile_picture_url

string(uri)

examplehttps://example.com/profile.png

websites

array

URLs of websites for the profile

vertical

string

exampleOTHER

The Industry or Business Category of the WhatsApp Profile

Must be one of:APPARELAUTOBEAUTYEDUENTERTAINEVENT_PLANFINANCEGOVTGROCERYHEALTHHOTELNONPROFITOTHERPROF_SERVICESRESTAURANTRETAILTRAVEL

Example Request

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

about

string

exampleAbout my business

Information about the profile

address

string

example123 Main Street, Anytown, USA

The address of the profile

description

string

exampleDescription of my business

The description of the profile

string

examplebob@example.com

The email address of the profile

profile_picture_url

string(uri)

examplehttps://example.com/profile.png

websites

array

URLs of websites for the profile

vertical

string

exampleOTHER

The Industry or Business Category of the WhatsApp Profile

Must be one of:APPARELAUTOBEAUTYEDUENTERTAINEVENT_PLANFINANCEGOVTGROCERYHEALTHHOTELNONPROFITOTHERPROF_SERVICESRESTAURANTRETAILTRAVEL

messaging_product

string

examplewhatsapp

The messaging product with which the profile is associated.

Must be one of:whatsapp

_links

object

self

object

Link to the current resource (always required in HAL)

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

WhatsApp Hosted ES Flow

API endpoints relating to working with WhatsApp Hosted Embedded Sign-up Flows

Available Operations

Generate Hosted ES Flow URL

Generate Hosted ES Flow URL

Generate a URL for the start page for WhatsApp hosted embedded sign-up flow based on the supplied partner solution ID.

posthttps://api.nexmo.com/v1/channel-manager/whatsapp/tp-registration/url

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Request Body
Content Type
application/json

solution_id

string

Required

example123456789111213

The partner solution ID.

api_key

string

exampleabc123

The API key of the Vonage account associated with the WhatsApp Business Account.

ttl

integer

Max259200

Default86400

example300

The time-to-live for the URL in seconds.

Example Request

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string

Required

example3amb0119-0196-42d1-8fb5-55a98s133546

The trace ID for the URL generation request.

url

string

Required

example

https://tools.vonage.com/wa/partners/onboard?token=fhdhhdJhbGciOiJSUzI1NiJ9.eyJleHAiOjE3MjU5Njc1OTYsImp0aSI6ImQ1MmJhNmFjLWYxZjktNDdmNC05MTR_cFT1bVfkDhP-wgpKZibSbUoh9z-9KGD-wsmHxi0h7tTidpVhPNShfC5jmgiHtOQKXXv5NWb9OqoUraOMMpqCdNdXoN3ao-PeZX7axyYW_FQ6CeV9gDEPhAZ4urTi0uW4mCYGl3ULmA9Ps92r_wi2DJyRE_Kx2KahWtQd51yVpU6FfXgMb4odREEccDctT1Peo09wKgwBa1wsOkD7rrvkoQPqZ00VXcqOY1_LOO5tq4WJaKqtxX-U7VtDo9qyVUl8pdegZW6QWChQzGN4PkqXXLWcBlyrCtAYdhtWG8q6NM_6bARRjcGJlj0tQvE0PZ9AtafAQSPpOll5lcnUK8Ds

URL containing tokenized information and redirecting to ES flow start page.

Example Response

WhatsApp Analytics

API endpoints relating to analytics data for WhatsApp

Available Operations

Get Template Analytics

Get analytics for a specific template.

gethttps://api.nexmo.com/v1/channel-manager/whatsapp/wabas/:waba_id/template-analytics

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

waba_id

string

Required

example345688589250625

The waba_id of the WhatsApp Business Account (WABA).

Query Parameters

template_ids

array

An array of the template_ids of the WhatsApp template(s).

start

string(timestamp)

example2024-11-01

The start date and time in ISO-8601 format for the analytics data to be retrieved from, in the format YYYY-MM-DD.

end

string(timestamp)

example2024-11-03

The end date and time in ISO-8601 format for the analytics data to be retrieved to, in the format YYYY-MM-DD. The maximum difference between the start and end dates is 90 days.

metric_types

array

example

[
  "SENT",
  "DELIVERED"
]

An array of the metric types to retrieve analytics for. Possible values are SENT, DELIVERED, READ, and CLICKED.

Available Values:

SENT,DELIVERED,READ,CLICKED

granularity

string

exampleDAILY

The granularity at which you would like to retrieve the template analytics.

Must be one of:DAILY

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

granularity

string

exampleDAILY

Must be one of:DAILY

product_type

string

exampleCLOUD_API

The product type for which the template analytics were retrieved.

Must be one of:CLOUD_APIMARKETING_MESSAGES_API_FOR_WHATSAPP

page_size

integer

example100

The maximum number of template analytics returned per page.

_embedded

object

template_analytics

array

template_id

string

Required

example458951126288942

The ID of the WhatsApp Template which the analytics data is for.

start

string(timestamp)

Required

example1543543200

The UNIX timestamp for the start of the data point range.

end

string(timestamp)

Required

example1543629600

The UNIX timestamp for the end of the data point range.

sent

integer

example100

The number of messages sent using the WhatsApp Template.

delivered

integer

example90

The number of messages delivered using the WhatsApp Template.

read

integer

example80

The number of messages read using the WhatsApp Template.

clicked

integer

example70

The number of messages clicked using the WhatsApp Template.

_links

object

self

object

href

string

example

https://api.nexmo.com/v1/channel-manager/whatsapp/wabas/345688589250625/template-analytics?template_ids=[458951126288937]&start=2024-11-10&end=2024-11-14&page_size=100&cursor=c2VsZj1udWxs

The URL to the current page of WhatsApp Template Analytics.

Example Response

Get Messaging Analytics

Get analytics for WhatsApp messages

gethttps://api.nexmo.com/v1/channel-manager/whatsapp/wabas/:waba_id/messaging-analytics

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

waba_id

string

Required

example345688589250625

The waba_id of the WhatsApp Business Account (WABA).

Query Parameters

granularity

string

exampleDAILY

The granularity at which you would like to retrieve the analytics.

Must be one of:HALF_HOURDAILYMONTHLY

start

string(timestamp)

example2024-11-01

The start date and time in ISO-8601 format for the analytics data to be retrieved from, in the format YYYY-MM-DD.

end

string(timestamp)

example2024-11-03

The end date and time in ISO-8601 format for the analytics data to be retrieved to, in the format YYYY-MM-DD. The maximum difference between the start and end dates is 90 days.

product_types

array

example

[
  0
]

An array of the message types to retrieve analytics for. Possible values are 0 for notification messages and/or 2 for customer support messages. If not specified, analytics for all message types will be returned.

Available Values:

0,2

phone_numbers

array

example

[
  "16505550111"
]

Phone numbers for which you would like to retrieve analytics. If not specified, analytics for all phone numbers associated with the WABA will be returned.

country_codes

array

example

[
  "US"
]

Two-letter country codes for the countries for which you would like to retrieve analytics. If not specified, analytics for all countries will be returned.

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string

example345688589250625

The ID of the WhatsApp Business Account.

granularity

string

exampleDAILY

Must be one of:HALF_HOURDAILYMONTHLY

phone_numbers

array

Phone numbers for which the messaging analytics were retrieved.

country_codes

array

_embedded

object

messaging_analytics

array

start

string(timestamp)

Required

example1543543200

The UNIX timestamp for the start of the data point range.

end

string(timestamp)

Required

example1543629600

The UNIX timestamp for the end of the data point range.

sent

integer

Required

example100

The number of messages sent using the WhatsApp Template.

delivered

integer

Required

example90

The number of messages delivered within the data point range.

paging

object

cursors

object

before

string

exampleMAZDZD

The page before the first page in the current list

after

string

exampleMjQZD

The page after the last page in the current list

string(uri)

examplehttps://api.nexmo.com/v2/channel-manager/wabas/106499765517625/messaging-analytics?after=MAZDZD

A URI to ge the next paginated page.

string(uri)

examplehttps://api.nexmo.com/v2/channel-manager/wabas/106499765517625/messaging-analytics?before=MjQZD

A URI to ge the previous paginated page.

Example Response

Get Pricing Analytics

Get analytics for message pricing.

gethttps://api.nexmo.com/v1/channel-manager/whatsapp/wabas/:waba_id/pricing-analytics

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

waba_id

string

Required

example345688589250625

The waba_id of the WhatsApp Business Account (WABA).

Query Parameters

start

string(timestamp)

example2024-11-01

The start date and time in ISO-8601 format for the analytics data to be retrieved from, in the format YYYY-MM-DD.

end

string(timestamp)

example2024-11-03

The end date and time in ISO-8601 format for the analytics data to be retrieved to, in the format YYYY-MM-DD. The maximum difference between the start and end dates is 90 days.

granularity

string

exampleDAILY

The granularity at which you would like to retrieve the analytics.

Must be one of:HALF_HOURDAILYMONTHLY

phone_numbers

array

example

[
  "16505550111"
]

Phone numbers for which you would like to retrieve analytics. If not specified, analytics for all phone numbers associated with the WABA will be returned.

country_codes

array

example

[
  "US"
]

Two-letter country codes for the countries for which you would like to retrieve analytics. If not specified, analytics for all countries will be returned.

dimensions

array

example

[
  "PRICING_CATEGORY"
]

List of breakdowns you would like to apply to your metrics. If empty, all results returned without any breakdowns.

Available Values:

PRICING_CATEGORY,PRICING_TYPE,COUNTRY,PHONE,TIER

tier

array

example

[
  "0:100000"
]

The tier property value represents a concatenation of the lower and upper bounds for the tier specific to the market–category pair (country and pricing_category).

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

granularity

string

exampleDAILY

Must be one of:HALF_HOURDAILYMONTHLY

product_type

string

exampleREGULAR

The product type for which the pricing analytics were retrieved.

Must be one of:FREE_CUSTOMER_SERVICEFREE_ENTRY_POINTREGULAR

_embedded

object

pricing_analytics

array

start

string(timestamp)

example1543543200

The UNIX timestamp for the start of the data point range.

end

string(timestamp)

example1543629600

The UNIX timestamp for the end of the data point range.

volume

integer

example100

The number of messages sent.

phone_number

string(e164)

example14155552671

The phone number associated with the Messaging Analytics.

country

string

exampleUS

The country for the phone number associated with the Messaging Analytics.

tier

string

example75000:150000

The pricing tier for the messages related to the Messaging Analytics.

pricing_type

string

exampleREGULAR

The pricing type for the messages related to the Messaging Analytics.

pricing_category

string

exampleAUTHENTICATION

The pricing category for the messages related to the Messaging Analytics.

paging

object

cursors

object

before

string

exampleMjQZD

The cursor the previous page of WhatsApp Pricing Analytics.

after

string

exampleMAZDZD

The cursor the next page of WhatsApp Pricing Analytics.

string

examplehttps://api.nexmo.com/v1/channel-manager/whatsapp/wabas/345688589250625/pricing-analytics?before=MjQZD

The URL to the previous page of WhatsApp Pricing Analytics.

string

examplehttps://api.nexmo.com/v1/channel-manager/whatsapp/wabas/345688589250625/pricing-analytics?before=MAZDZD

The URL to the next page of WhatsApp Pricing Analytics.

Example Response

Enable template analytics

Before you can fetch template analytics, Meta guidelines ask you to enable "insights". This endpoint will enable insights

patchhttps://api.nexmo.com/v1/channel-manager/whatsapp/wabas/:waba_id/enable_insights

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

waba_id

string

Required

example345688589250625

The waba_id of the WhatsApp Business Account (WABA).

Responses

No Content - Resource successfully deleted

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

WhatsApp Notification Subscriptions

API endpoints relating to subscriptions for WhatsApp Notification

Available Operations

List Notification Subscriptions

Get a list of all notification subscriptions for the main API key

gethttps://api.nexmo.com/v2/whatsapp-manager/subscriptions

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

array

Any Of

label

string

exampleMy WhatsApp Subscription

An optional label for the subscription

whatsapp_subscribe_types

string

exampleaccount_alerts,account_update

A comma-separated list of the WhatsApp notification types that the subscription is for. Supports all the notification types available for WhatsApp accounts listed here. When a new subscription is created, if this parameter is not specified then the subscription will include all of the subscription types.

vonage_subscribe_types

string

examplevonage_number_onboarded

A comma-separated list of the Vonage notification types that the subscription is for.

Must be one of:vonage_number_onboarded

created_at

string

example2024-11-01T12:00:00Z

The date and time when the subscription was created, in ISO-8601 format.

string

example9fa85698-c92a-4786-be0e-b5a489425120

The unique ID of the subscription

type

string

exampleslack

The subscription type

Must be one of:slack

slack

object

Required

The Slack hook configuration for the subscription, where the subscription type is slack.

url

string(uri)

Required

examplehttps://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

The URL of the Slack hook to which the WhatsApp notifications will be sent

Example Response

Create a Notification Subscription

Create a new notification subscription for the main API key

posthttps://api.nexmo.com/v2/whatsapp-manager/subscriptions

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Request Body
Content Type
application/json

One Of

label

string

exampleMy WhatsApp Subscription

An optional label for the subscription

whatsapp_subscribe_types

string

exampleaccount_alerts,account_update

vonage_subscribe_types

string

examplevonage_number_onboarded

A comma-separated list of the Vonage notification types that the subscription is for.

Must be one of:vonage_number_onboarded

created_at

string

example2024-11-01T12:00:00Z

The date and time when the subscription was created, in ISO-8601 format.

string

example9fa85698-c92a-4786-be0e-b5a489425120

The unique ID of the subscription

type

string

exampleslack

The subscription type

Must be one of:slack

slack

object

Required

The Slack hook configuration for the subscription, where the subscription type is slack.

url

string(uri)

Required

examplehttps://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

The URL of the Slack hook to which the WhatsApp notifications will be sent

Example Request

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

One Of

label

string

exampleMy WhatsApp Subscription

An optional label for the subscription

whatsapp_subscribe_types

string

exampleaccount_alerts,account_update

vonage_subscribe_types

string

examplevonage_number_onboarded

A comma-separated list of the Vonage notification types that the subscription is for.

Must be one of:vonage_number_onboarded

created_at

string

example2024-11-01T12:00:00Z

The date and time when the subscription was created, in ISO-8601 format.

string

example9fa85698-c92a-4786-be0e-b5a489425120

The unique ID of the subscription

type

string

exampleslack

The subscription type

Must be one of:slack

slack

object

Required

The Slack hook configuration for the subscription, where the subscription type is slack.

url

string(uri)

Required

examplehttps://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

The URL of the Slack hook to which the WhatsApp notifications will be sent

Example Response

Delete a Notification Subscription

Delete a notification subscription for the main API key

deletehttps://api.nexmo.com/v2/whatsapp-manager/subscriptions/:subscription_id

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

subscription_id

string

Required

example9fa85698-c92a-4786-be0e-b5a489425120

The ID of the notification subscription to delete.

Responses

No Content - Resource successfully deleted

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

RCS Capability Checks

API endpoints relating to checking RCS capabilities of a device or devices

Available Operations

RCS Capabilities Device Check

Get RCS Capabilities for a Specific Device. Please note that this operation is deprecated, please refer to this one instead.

gethttps://api.nexmo.com/v1/channel-manager/rcs/agents/:sender_id/google/phones/:phone_number/capabilities

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Path Parameters

sender_id

string

Required

exampleVonageAgent

The Sender ID of your RCS Agent.

phone_number

string(e164)

Required

example447700900001

The phone number of the device to check.

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

features

array

A list of RCS capabilities for the device being checked.

Available Values:

RICHCARD_STANDALONE,RICHCARD_CAROUSEL,ACTION_CREATE_CALENDAR_EVENT,ACTION_DIAL,ACTION_OPEN_URL,ACTION_SHARE_LOCATION,ACTION_VIEW_LOCATION

Example Response

RCS Capabilities Device Check

Get RCS Capabilities for a Specific Device

posthttps://api.nexmo.com/v1/channel-manager/rcs/agents/:sender_id/devices/capabilities

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

sender_id

string

Required

exampleVonageAgent

The Sender ID of your RCS Agent.

Request Body
Content Type
application/json

msisdn

string(e164)

Required

example447700900001

E.164 formatted phone number without + prefix

country

string

Required

exampleGB

The country code of the device to check.

Example Request

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

rcs_supported

boolean

exampletrue

Indicates if RCS is supported on the device.

features

array

A list of RCS capabilities for the device being checked.

Available Values:

RICHCARD_STANDALONE,RICHCARD_CAROUSEL,ACTION_CREATE_CALENDAR_EVENT,ACTION_DIAL,ACTION_OPEN_URL,ACTION_SHARE_LOCATION,ACTION_VIEW_LOCATION

Example Response

RCS Capabilities Bulk Check

Perform an RCS Capability Check for Multiple Devices. See the RCS Capability Checks documentation for more information.

posthttps://api.nexmo.com/v1/channel-manager/rcs/agents/:sender_id/google/:operation

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Path Parameters

sender_id

string

Required

exampleVonageAgent

The Sender ID of your RCS Agent.

operation

string

Required

The operation to perform.

Must be one of:users:batchGet

Request Body
Content Type
application/json

users

array

An array of phone numbers to check.

Example Request

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

One Of

reachableUsers

array

A list of specific numbers for devices that reachable for RCS messaging.

Example Response»Response where 500 numbers or less submitted.

RCS Opt-out Management

API endpoints relating to managing RCS opt-outs

Available Operations

Get Opt-out Information

Retrieve RCS Opt-out information. Note: this feature is only available to accounts with RCS enabled; please contact your Vonage representative for more information.

gethttps://api.nexmo.com/v1/channel-manager/rcs/opt-out/:sender_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

sender_id

string

Required

exampleVonageAgent

The Sender ID of your RCS Agent.

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

enabled

boolean

exampletrue

Indicates if opt-out is enabled for the user.

actions

array

Required

A list of actions available for opt-out.

keywords

array

Required

A list of keywords that trigger the action.

auto-reply

string

Required

exampleYou have opted out.

The auto-reply message sent when the action is triggered.

action

string

Required

exampleSTOP

The type of action.

Must be one of:STOPSTARTCUSTOM

Example Response

Update Opt-out Information

Update RCS Opt-out information. Note: this feature is only available to accounts with RCS enabled; please contact your Vonage representative for more information.

posthttps://api.nexmo.com/v1/channel-manager/rcs/opt-out/:sender_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

sender_id

string

Required

exampleVonageAgent

The Sender ID of your RCS Agent.

Request Body
Content Type
application/json

enabled

boolean

exampletrue

Indicates if opt-out is enabled for the user.

actions

array

Required

A list of actions available for opt-out.

keywords

array

Required

A list of keywords that trigger the action.

auto-reply

string

Required

exampleYou have opted out.

The auto-reply message sent when the action is triggered.

action

string

Required

exampleSTOP

The type of action.

Must be one of:STOPSTARTCUSTOM

Example Request

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

enabled

boolean

exampletrue

Indicates if opt-out is enabled for the user.

actions

array

Required

A list of actions available for opt-out.

keywords

array

Required

A list of keywords that trigger the action.

auto-reply

string

Required

exampleYou have opted out.

The auto-reply message sent when the action is triggered.

action

string

Required

exampleSTOP

The type of action.

Must be one of:STOPSTARTCUSTOM

Example Response

RCS Brand Management

API endpoints relating to managing RCS Brands

Available Operations

List Brands (Deprecated)

Retrieve a list of RCS Brands. Deprecated, please use the v2 endpoint instead.

gethttps://api.nexmo.com/v1/channel-manager/rcs/brands

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

array

brands

array

Required

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the RCS Brand.

display_name

string

Required

exampleMy RCS Brand

The name of the RCS Brand.

Example Response

Create Brand (Deprecated)

Create a new RCS Brand. Deprecated, please use the v2 endpoint instead.

posthttps://api.nexmo.com/v1/channel-manager/rcs/brands

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Request Body
Content Type
application/json

display_name

string

Required

exampleMy RCS Brand

The name of the RCS Brand.

Example Request

Responses
Content Type
application/json

Created

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the RCS Brand.

display_name

string

Required

exampleMy RCS Brand

The name of the RCS Brand.

Example Response

{
   "id": "78d335fa-323d-0114-9c3d-d6f0d48968cf",
   "display_name": "My RCS Brand"
}

Update Brand (Deprecated)

Update an existing RCS Brand. Deprecated, please use the v2 endpoint instead.

patchhttps://api.nexmo.com/v1/channel-manager/rcs/brands/:brand_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

brand_id

string

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The Id of the Brand.

Request Body
Content Type
application/json

display_name

string

Required

exampleMy RCS Brand

The name of the RCS Brand.

Example Request

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the RCS Brand.

display_name

string

Required

exampleMy RCS Brand

The name of the RCS Brand.

Example Response

Delete Brand (Deprecated)

Delete an existing RCS Brand. Deprecated, please use the v2 endpoint instead.

deletehttps://api.nexmo.com/v1/channel-manager/rcs/brands/:brand_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

brand_id

string

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The Id of the Brand.

Responses

No Content - Resource successfully deleted

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

List Brands

Retrieve a list of RCS Brands.

gethttps://api.nexmo.com/v2/channel-manager/rcs/brands

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

array

brands

array

Required

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the RCS Brand.

display_name

string

Required

Max100

exampleMy RCS Brand

The name of the RCS Brand.

details

object

organization_name

string

Required

Max255

exampleAcme Corporation

Legal organization name

legal_form

string

Required

Max50

exampleLimited liability company (LLC)

Legal form of the organization. When a standard value matches your case, use it exactly as listed to ensure consistency.

Standard values for US entities:

Limited liability company (LLC)
Corporation (C-corp)
Benefit Corporation (B-corp)
Partnership (General or Limited)
Nonprofit or Foundation
Sole proprietorship

Standard values for non-US entities:

Private limited company
Public limited company
Sole proprietorship
Partnership
Nonprofit or Foundation

Custom values are accepted when none of the above apply.

stock_symbol

string

Max12

exampleACME

Stock symbol of the organization, if publicly traded

legal_entity_type

string

Required

Max50

examplePrivate

Type of legal entity. When a standard value matches your case, use it exactly as listed to ensure consistency.

Standard values:

Public
Private
Government
Non-profit
Sole proprietor

Custom values are accepted when none of the above apply.

country_of_registration

string

Required

Min2

Max2

exampleUS

ISO 3166-1 alpha-2 country code of registration

federal_tax_id

string

Max50

example12-3456789

Federal tax identification number (required for US entities)

business_website_url

string

Required

Max255

examplehttps://www.example.com

Business website URL of the organization

address_line1

string

Required

Max255

exampleOne Main Street

Primary address line

address_line2

string

Max255

exampleSuite 100

Secondary address line

city

string

Required

Max100

exampleSan Francisco

City name

state_or_province

string

Required

Max100

exampleCalifornia

State or province name

zip_or_post_code

string

Required

Max15

exampleSW1A 1AA

ZIP or postal code

Example Response

Create Brand

Create a new RCS Brand.

posthttps://api.nexmo.com/v2/channel-manager/rcs/brands

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Request Body
Content Type
application/json

display_name

string

Required

Max100

exampleMy RCS Brand

The name of the RCS Brand.

details

object

organization_name

string

Required

Max255

exampleAcme Corporation

Legal organization name

legal_form

string

Required

Max50

exampleLimited liability company (LLC)

Legal form of the organization. When a standard value matches your case, use it exactly as listed to ensure consistency.

Standard values for US entities:

Limited liability company (LLC)
Corporation (C-corp)
Benefit Corporation (B-corp)
Partnership (General or Limited)
Nonprofit or Foundation
Sole proprietorship

Standard values for non-US entities:

Private limited company
Public limited company
Sole proprietorship
Partnership
Nonprofit or Foundation

Custom values are accepted when none of the above apply.

stock_symbol

string

Max12

exampleACME

Stock symbol of the organization, if publicly traded

legal_entity_type

string

Required

Max50

examplePrivate

Type of legal entity. When a standard value matches your case, use it exactly as listed to ensure consistency.

Standard values:

Public
Private
Government
Non-profit
Sole proprietor

Custom values are accepted when none of the above apply.

country_of_registration

string

Required

Min2

Max2

exampleUS

ISO 3166-1 alpha-2 country code of registration

federal_tax_id

string

Max50

example12-3456789

Federal tax identification number (required for US entities)

business_website_url

string

Required

Max255

examplehttps://www.example.com

Business website URL of the organization

address_line1

string

Required

Max255

exampleOne Main Street

Primary address line

address_line2

string

Max255

exampleSuite 100

Secondary address line

city

string

Required

Max100

exampleSan Francisco

City name

state_or_province

string

Required

Max100

exampleCalifornia

State or province name

zip_or_post_code

string

Required

Max15

exampleSW1A 1AA

ZIP or postal code

Example Request

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the RCS Brand.

display_name

string

Required

Max100

exampleMy RCS Brand

The name of the RCS Brand.

details

object

organization_name

string

Required

Max255

exampleAcme Corporation

Legal organization name

legal_form

string

Required

Max50

exampleLimited liability company (LLC)

Legal form of the organization. When a standard value matches your case, use it exactly as listed to ensure consistency.

Standard values for US entities:

Limited liability company (LLC)
Corporation (C-corp)
Benefit Corporation (B-corp)
Partnership (General or Limited)
Nonprofit or Foundation
Sole proprietorship

Standard values for non-US entities:

Private limited company
Public limited company
Sole proprietorship
Partnership
Nonprofit or Foundation

Custom values are accepted when none of the above apply.

stock_symbol

string

Max12

exampleACME

Stock symbol of the organization, if publicly traded

legal_entity_type

string

Required

Max50

examplePrivate

Type of legal entity. When a standard value matches your case, use it exactly as listed to ensure consistency.

Standard values:

Public
Private
Government
Non-profit
Sole proprietor

Custom values are accepted when none of the above apply.

country_of_registration

string

Required

Min2

Max2

exampleUS

ISO 3166-1 alpha-2 country code of registration

federal_tax_id

string

Max50

example12-3456789

Federal tax identification number (required for US entities)

business_website_url

string

Required

Max255

examplehttps://www.example.com

Business website URL of the organization

address_line1

string

Required

Max255

exampleOne Main Street

Primary address line

address_line2

string

Max255

exampleSuite 100

Secondary address line

city

string

Required

Max100

exampleSan Francisco

City name

state_or_province

string

Required

Max100

exampleCalifornia

State or province name

zip_or_post_code

string

Required

Max15

exampleSW1A 1AA

ZIP or postal code

Example Response

Update Brand

Update an existing RCS Brand.

patchhttps://api.nexmo.com/v2/channel-manager/rcs/brands/:brand_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

brand_id

string

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The Id of the Brand.

Request Body
Content Type
application/json

display_name

string

Max100

exampleMy RCS Brand

The name of the RCS Brand.

details

object

organization_name

string

Required

Max255

exampleAcme Corporation

Legal organization name

legal_form

string

Required

Max50

exampleLimited liability company (LLC)

Legal form of the organization. When a standard value matches your case, use it exactly as listed to ensure consistency.

Standard values for US entities:

Limited liability company (LLC)
Corporation (C-corp)
Benefit Corporation (B-corp)
Partnership (General or Limited)
Nonprofit or Foundation
Sole proprietorship

Standard values for non-US entities:

Private limited company
Public limited company
Sole proprietorship
Partnership
Nonprofit or Foundation

Custom values are accepted when none of the above apply.

stock_symbol

string

Max12

exampleACME

Stock symbol of the organization, if publicly traded

legal_entity_type

string

Required

Max50

examplePrivate

Type of legal entity. When a standard value matches your case, use it exactly as listed to ensure consistency.

Standard values:

Public
Private
Government
Non-profit
Sole proprietor

Custom values are accepted when none of the above apply.

country_of_registration

string

Required

Min2

Max2

exampleUS

ISO 3166-1 alpha-2 country code of registration

federal_tax_id

string

Max50

example12-3456789

Federal tax identification number (required for US entities)

business_website_url

string

Required

Max255

examplehttps://www.example.com

Business website URL of the organization

address_line1

string

Required

Max255

exampleOne Main Street

Primary address line

address_line2

string

Max255

exampleSuite 100

Secondary address line

city

string

Required

Max100

exampleSan Francisco

City name

state_or_province

string

Required

Max100

exampleCalifornia

State or province name

zip_or_post_code

string

Required

Max15

exampleSW1A 1AA

ZIP or postal code

Example Request

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the RCS Brand.

display_name

string

Required

Max100

exampleMy RCS Brand

The name of the RCS Brand.

details

object

organization_name

string

Required

Max255

exampleAcme Corporation

Legal organization name

legal_form

string

Required

Max50

exampleLimited liability company (LLC)

Legal form of the organization. When a standard value matches your case, use it exactly as listed to ensure consistency.

Standard values for US entities:

Limited liability company (LLC)
Corporation (C-corp)
Benefit Corporation (B-corp)
Partnership (General or Limited)
Nonprofit or Foundation
Sole proprietorship

Standard values for non-US entities:

Private limited company
Public limited company
Sole proprietorship
Partnership
Nonprofit or Foundation

Custom values are accepted when none of the above apply.

stock_symbol

string

Max12

exampleACME

Stock symbol of the organization, if publicly traded

legal_entity_type

string

Required

Max50

examplePrivate

Type of legal entity. When a standard value matches your case, use it exactly as listed to ensure consistency.

Standard values:

Public
Private
Government
Non-profit
Sole proprietor

Custom values are accepted when none of the above apply.

country_of_registration

string

Required

Min2

Max2

exampleUS

ISO 3166-1 alpha-2 country code of registration

federal_tax_id

string

Max50

example12-3456789

Federal tax identification number (required for US entities)

business_website_url

string

Required

Max255

examplehttps://www.example.com

Business website URL of the organization

address_line1

string

Required

Max255

exampleOne Main Street

Primary address line

address_line2

string

Max255

exampleSuite 100

Secondary address line

city

string

Required

Max100

exampleSan Francisco

City name

state_or_province

string

Required

Max100

exampleCalifornia

State or province name

zip_or_post_code

string

Required

Max15

exampleSW1A 1AA

ZIP or postal code

Example Response

Delete Brand

Delete an existing RCS Brand.

deletehttps://api.nexmo.com/v2/channel-manager/rcs/brands/:brand_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

brand_id

string

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The Id of the Brand.

Responses

No Content - Resource successfully deleted

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

RCS Agent Management

API endpoints relating to managing RCS Agents

Available Operations

List Agents (Deprecated)

Retrieve a list of RCS Agents. Deprecated, please use the v2 endpoint instead.

gethttps://api.nexmo.com/v1/channel-manager/rcs/agents

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Query Parameters

brand_id

string(uuid)

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

The id of an RCS Brand to filter by.

state

string

exampleDRAFT

The state of the RCS Agent to filter by.

Must be one of:DRAFTCREATEDVERIFIEDLAUNCHEDREJECTEDUNLAUNCHED

agent_purpose

string

exampleTRANSACTIONAL

The agent_purpose of the RCS Agent to filter by.

Must be one of:PROMOTIONALTRANSACTIONALOTPMULTI_USE

billing_category

string

exampleCONVERSATIONAL

The billing_category of the RCS Agent to filter by.

Must be one of:CONVERSATIONALNON_CONVERSATIONAL

hosting_region

string

exampleNORTH_AMERICA

The hosting_region of the RCS Agent to filter by.

Must be one of:NORTH_AMERICAEUROPEASIA_PACIFIC

page

integer

Min1

Default1

example1

Page number to retrieve

page_size

integer

Min1

Default10

example20

Number of items to return per page

order

string

The order.

Must be one of:ascdesc

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

page

integer

Required

Min1

Default1

example1

The current page

page_size

integer

Required

Min1

Default10

example20

The size of the page

total_items

integer

Required

example871

The total number of items in the resource list

total_pages

integer

Required

Min1

example42

Total number of pages

_embedded

object

Required

agents

array

Required

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the created RCS Agent.

state

string

exampleDRAFT

The current state of the created RCS Agent.

application_settings

object

application_id

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The id of the Vonage application with which to associate this agent.

basic_info

object

Required

brand_id

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the RCS Brand.

display_name

string

Required

exampleExample Co

The unique display name of the RCS Agent.

sender_id

string

Required

exampleExampleCo-RCSAgentv1-1

A unique sender identifier on the Vonage platform. This cannot be blank, include whitespaces, or be changed after creation. The sender ID is used as the from value when sending RCS messages via the Messages API.

hosting_region

string

Required

exampleNORTH_AMERICA

The geographic location where your RCS business messaging service will be hosted and operated. This can affect data residency and compliance requirements.

Must be one of:NORTH_AMERICAEUROPEASIA_PACIFIC

agent_purpose

string

Required

exampleTRANSACTIONAL

Specifies the intended use of the RCS Agent. This cannot be changed after creation.

Must be one of:PROMOTIONALTRANSACTIONALOTPMULTI_USE

billing_category

string

Required

exampleCONVERSATIONAL

Specifies the billing category of the RCS Agent.

Must be one of:CONVERSATIONALNON_CONVERSATIONAL

notes

string

exampleThis agent is used for transactional messages only.

Additional notes or comments about the RCS Agent.

DEPRECATED This parameter is deprecated and will be removed in future. It can still be included in the request for backward compatibility, but it will not have any effect on the RCS Agent.

carrier_requirements

object

agent_preview

object

Required

agent_access_instructions

string

Required

example

Provide a method for reviewers to trigger the agent, such as a website where reviewers can invite and add phone numbers. 
If you need a list of phone numbers to add as test devices, contact rbm-support@vonage.com. 
Test the agent by sending a keyword like 'HELP' or 'START' to initiate conversation flow.

Agent access instructions specify how reviewers and testers can access and interact with your RBM agent during the review and testing phases before launch. This property provides guidance on methods for triggering agent functionality and testing various features.

urls

array

media_type

string

Required

exampleimage

The media type of the agent preview.

Must be one of:imagevideo

url

string(uri)

examplehttps://www.example.com/rcs-agent-preview.jpg

The URL to the agent preview.

points_of_contact

array

Required

A list of points of contact for the RCS Agent.

first_name

string

Required

Max200

exampleJohn

The first name of the representative for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the representative for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the representative.

brand_website

string(uri)

examplehttps://www.example.com

The website URL of the brand represented by the RCS Agent.

job_title

string

Required

Max200

exampleTechnical Support

The job title of the point of contact.

traffic_estimates

object

Required

Traffic estimates for the RCS Agent.

average_global_traffic

string

Required

exampleTHOUSAND

Estimated global traffic.

Must be one of:THOUSANDTEN_THOUSANDFIFTY_THOUSANDHUNDRED_THOUSANDMILLIONMILLION_AND_MORE

average_message_rate_per_user

string

Required

exampleONCE_PER_MONTH

Estimated message rate per user.

Must be one of:ONCE_PER_MONTH2_4_TIMES_PER_MONTHONCE_PER_WEEK2_6_TIMES_PER_WEEKDAILYMULTIPLE_TIMES_PER_DAY

users_targeted

string

Required

exampleHUNDRED

Estimated number of users targeted.

Must be one of:HUNDREDTHOUSANDTEN_THOUSANDHUNDRED_THOUSANDHALF_MILLIONMILLIONMILLION_AND_MORE

user_experience

object

Required

interactions_description

string

Required

Max10000

example

This agent handles customer support inquiries and provides product information. Primary interactions include order status updates, account notifications, and FAQ responses. 
Secondary interactions may include promotional offers for existing customers and appointment scheduling assistance.

This field describes the primary and secondary types of interactions your RBM agent will have with users. It outlines the conversational patterns, message types, and engagement scenarios your agent supports.

optin_description

string

Required

Max10000

example

This is a test environment. Customers consent to receive messages directly via request, phone, or email. 
Users can opt-in by visiting our website and providing their phone number, or by texting 'JOIN' to our SMS shortcode. 
Opt-in confirmation includes details about message frequency and content type.

Details how users will provide consent to receive messages from your RBM agent. This must clearly explain the opt-in mechanism and what users can expect when they subscribe to your messaging service.

optout_description

string

Required

Max10000

example

Customers can unsubscribe from receiving messages by replying 'STOP' to any message. 
They can also contact us by email at support@company.com. Users will receive a confirmation message when successfully unsubscribed, 
and can re-subscribe at any time by replying 'START'.

Explains how users can unsubscribe from receiving messages from your agent. Must describe the process for users to stop receiving communications and how your system handles these requests.

trigger_description

string

Required

Max10000

example

This account is used exclusively for sending test messages to introduce RCS capabilities to customers. 
Triggers include: order placement confirmations, shipping notifications, appointment reminders, customer service escalations, 
and weekly promotional campaigns for opted-in users.

Defines the external events or conditions that will cause your RBM agent to initiate conversations with users. These triggers determine when and why your agent sends the first message to users.

visual_design

object

brand_color

string

Required

example#8860CD

The hexadecimal color code for the primary color used in UI elements. The specified color must meet WCAG 2.1 contrast ratio of 4.5:1 for legibility.

array

Required

address

string

Required

examplesupport@example.com

The contact email address for the RCS Agent.

label

string

Max25

exampleCustomer Support

A label for the email address.

phone

array

Required

number

string(e164)

Required

example447700900001

E.164 formatted phone number without + prefix

label

string

Max25

exampleCustomer Support

A label for the phone number.

tagline

string

Required

Max100

exampleYour trusted partner in messaging.

A short phrase that represents the RCS Agent.

website

array

Required

url

string(uri)

Required

examplehttps://example.com

label

string

Max25

exampleCompany Website

A label for the website URL.

logo_image

string(uri)

Required

examplehttps://agent-logos.storage.googleapis.com/_/mbsy6ycz7BnqOi4WKZlOmpkz

A publicly available URL of the logo image for the RCS Agent. The image must be 224px x 224px, with minimum contrast ratio of 4.5:1 against a white background. Maximum file size of 50 KB. Supported types:

image/png
image/jpeg
image/jpg

Any image file not meeting the requirements will result in an error response. The logo image is not modifiable after agent verification.

banner_image

string(uri)

Required

examplehttps://agent-logos.storage.googleapis.com/_/mbsy64um0BwndPRK8ECPyeqb

A publicly available URL of the hero image for the RCS Agent. The image must be 1440px x 448px, with minimum contrast ratio of 4.5:1 against a white background. Maximum file size of 200 KB. Supported types:

image/png
image/jpeg
image/jpg

Any image file not meeting the requirements will result in an error response. The banner image is not modifiable after agent verification.

privacy_policy

string(uri)

examplehttps://www.example.com/privacy-policy

The publicly accessible URL of the privacy policy for the RCS Agent.

terms_of_service

string(uri)

examplehttps://www.example.com/terms-of-service

The publicly accessible URL of the terms of service for the RCS Agent.

representative

object

first_name

string

Required

Max200

exampleJohn

The first name of the representative for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the representative for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the representative.

brand_website

string(uri)

examplehttps://www.example.com

The website URL of the brand represented by the RCS Agent.

created_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent was created.

updated_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent was last updated.

test_devices

array

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The id of the test device.

phone

string(e164)

Required

example447700900001

E.164 formatted phone number without + prefix

status

string

Required

exampleACCEPTED

The current status of the test device.

created_at

string

Required

example2023-01-01T12:00:00Z

The date and time when the test device was created.

carriers

object

string

Required

exampleatt-us

The id of the carrier.

launch_state

string

exampleLAUNCH_STATE_UNLAUNCHED

The launch state of the carrier.

Must be one of:LAUNCH_STATE_UNSPECIFIEDLAUNCH_STATE_UNLAUNCHEDLAUNCH_STATE_PENDINGLAUNCH_STATE_LAUNCHEDLAUNCH_STATE_REJECTEDLAUNCH_STATE_SUSPENDEDLAUNCH_STATE_PENDING_UNLAUNCHLAUNCH_STATE_INVALID_IN_GMB

verification_details

object

status

string

exampleVERIFICATION_STATE_UNVERIFIED

The verification status of the RCS Agent.

launch_submitted_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent launch was submitted.

_links

object

Required

HAL links for page-based paginated collections

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

first

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

object

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

object

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

last

object

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

Create Agent (Deprecated)

Create a new RCS Agent. Deprecated, please use the v2 endpoint instead.

posthttps://api.nexmo.com/v1/channel-manager/rcs/agents

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Request Body
Content Type
application/json

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the created RCS Agent.

state

string

exampleDRAFT

The current state of the created RCS Agent.

application_settings

object

application_id

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The id of the Vonage application with which to associate this agent.

basic_info

object

Required

brand_id

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the RCS Brand.

display_name

string

Required

exampleExample Co

The unique display name of the RCS Agent.

sender_id

string

Required

exampleExampleCo-RCSAgentv1-1

hosting_region

string

Required

exampleNORTH_AMERICA

The geographic location where your RCS business messaging service will be hosted and operated. This can affect data residency and compliance requirements.

Must be one of:NORTH_AMERICAEUROPEASIA_PACIFIC

agent_purpose

string

Required

exampleTRANSACTIONAL

Specifies the intended use of the RCS Agent. This cannot be changed after creation.

Must be one of:PROMOTIONALTRANSACTIONALOTPMULTI_USE

billing_category

string

Required

exampleCONVERSATIONAL

Specifies the billing category of the RCS Agent.

Must be one of:CONVERSATIONALNON_CONVERSATIONAL

notes

string

exampleThis agent is used for transactional messages only.

Additional notes or comments about the RCS Agent.

DEPRECATED This parameter is deprecated and will be removed in future. It can still be included in the request for backward compatibility, but it will not have any effect on the RCS Agent.

carrier_requirements

object

agent_preview

object

Required

agent_access_instructions

string

Required

example

Provide a method for reviewers to trigger the agent, such as a website where reviewers can invite and add phone numbers. 
If you need a list of phone numbers to add as test devices, contact rbm-support@vonage.com. 
Test the agent by sending a keyword like 'HELP' or 'START' to initiate conversation flow.

urls

array

media_type

string

Required

exampleimage

The media type of the agent preview.

Must be one of:imagevideo

url

string(uri)

examplehttps://www.example.com/rcs-agent-preview.jpg

The URL to the agent preview.

points_of_contact

array

Required

A list of points of contact for the RCS Agent.

first_name

string

Required

Max200

exampleJohn

The first name of the representative for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the representative for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the representative.

brand_website

string(uri)

examplehttps://www.example.com

The website URL of the brand represented by the RCS Agent.

job_title

string

Required

Max200

exampleTechnical Support

The job title of the point of contact.

traffic_estimates

object

Required

Traffic estimates for the RCS Agent.

average_global_traffic

string

Required

exampleTHOUSAND

Estimated global traffic.

Must be one of:THOUSANDTEN_THOUSANDFIFTY_THOUSANDHUNDRED_THOUSANDMILLIONMILLION_AND_MORE

average_message_rate_per_user

string

Required

exampleONCE_PER_MONTH

Estimated message rate per user.

Must be one of:ONCE_PER_MONTH2_4_TIMES_PER_MONTHONCE_PER_WEEK2_6_TIMES_PER_WEEKDAILYMULTIPLE_TIMES_PER_DAY

users_targeted

string

Required

exampleHUNDRED

Estimated number of users targeted.

Must be one of:HUNDREDTHOUSANDTEN_THOUSANDHUNDRED_THOUSANDHALF_MILLIONMILLIONMILLION_AND_MORE

user_experience

object

Required

interactions_description

string

Required

Max10000

example

This agent handles customer support inquiries and provides product information. Primary interactions include order status updates, account notifications, and FAQ responses. 
Secondary interactions may include promotional offers for existing customers and appointment scheduling assistance.

optin_description

string

Required

Max10000

example

This is a test environment. Customers consent to receive messages directly via request, phone, or email. 
Users can opt-in by visiting our website and providing their phone number, or by texting 'JOIN' to our SMS shortcode. 
Opt-in confirmation includes details about message frequency and content type.

Details how users will provide consent to receive messages from your RBM agent. This must clearly explain the opt-in mechanism and what users can expect when they subscribe to your messaging service.

optout_description

string

Required

Max10000

example

Customers can unsubscribe from receiving messages by replying 'STOP' to any message. 
They can also contact us by email at support@company.com. Users will receive a confirmation message when successfully unsubscribed, 
and can re-subscribe at any time by replying 'START'.

Explains how users can unsubscribe from receiving messages from your agent. Must describe the process for users to stop receiving communications and how your system handles these requests.

trigger_description

string

Required

Max10000

example

This account is used exclusively for sending test messages to introduce RCS capabilities to customers. 
Triggers include: order placement confirmations, shipping notifications, appointment reminders, customer service escalations, 
and weekly promotional campaigns for opted-in users.

Defines the external events or conditions that will cause your RBM agent to initiate conversations with users. These triggers determine when and why your agent sends the first message to users.

visual_design

object

brand_color

string

Required

example#8860CD

The hexadecimal color code for the primary color used in UI elements. The specified color must meet WCAG 2.1 contrast ratio of 4.5:1 for legibility.

array

Required

address

string

Required

examplesupport@example.com

The contact email address for the RCS Agent.

label

string

Max25

exampleCustomer Support

A label for the email address.

phone

array

Required

number

string(e164)

Required

example447700900001

E.164 formatted phone number without + prefix

label

string

Max25

exampleCustomer Support

A label for the phone number.

tagline

string

Required

Max100

exampleYour trusted partner in messaging.

A short phrase that represents the RCS Agent.

website

array

Required

url

string(uri)

Required

examplehttps://example.com

label

string

Max25

exampleCompany Website

A label for the website URL.

logo_image

string(uri)

Required

examplehttps://agent-logos.storage.googleapis.com/_/mbsy6ycz7BnqOi4WKZlOmpkz

image/png
image/jpeg
image/jpg

Any image file not meeting the requirements will result in an error response. The logo image is not modifiable after agent verification.

banner_image

string(uri)

Required

examplehttps://agent-logos.storage.googleapis.com/_/mbsy64um0BwndPRK8ECPyeqb

image/png
image/jpeg
image/jpg

Any image file not meeting the requirements will result in an error response. The banner image is not modifiable after agent verification.

privacy_policy

string(uri)

examplehttps://www.example.com/privacy-policy

The publicly accessible URL of the privacy policy for the RCS Agent.

terms_of_service

string(uri)

examplehttps://www.example.com/terms-of-service

The publicly accessible URL of the terms of service for the RCS Agent.

representative

object

first_name

string

Required

Max200

exampleJohn

The first name of the representative for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the representative for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the representative.

brand_website

string(uri)

examplehttps://www.example.com

The website URL of the brand represented by the RCS Agent.

created_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent was created.

updated_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent was last updated.

Example Request

Responses
Content Type
application/json

Created

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the created RCS Agent.

state

string

exampleDRAFT

The current state of the created RCS Agent.

application_settings

object

application_id

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The id of the Vonage application with which to associate this agent.

basic_info

object

Required

brand_id

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the RCS Brand.

display_name

string

Required

exampleExample Co

The unique display name of the RCS Agent.

sender_id

string

Required

exampleExampleCo-RCSAgentv1-1

hosting_region

string

Required

exampleNORTH_AMERICA

The geographic location where your RCS business messaging service will be hosted and operated. This can affect data residency and compliance requirements.

Must be one of:NORTH_AMERICAEUROPEASIA_PACIFIC

agent_purpose

string

Required

exampleTRANSACTIONAL

Specifies the intended use of the RCS Agent. This cannot be changed after creation.

Must be one of:PROMOTIONALTRANSACTIONALOTPMULTI_USE

billing_category

string

Required

exampleCONVERSATIONAL

Specifies the billing category of the RCS Agent.

Must be one of:CONVERSATIONALNON_CONVERSATIONAL

notes

string

exampleThis agent is used for transactional messages only.

Additional notes or comments about the RCS Agent.

DEPRECATED This parameter is deprecated and will be removed in future. It can still be included in the request for backward compatibility, but it will not have any effect on the RCS Agent.

carrier_requirements

object

agent_preview

object

Required

agent_access_instructions

string

Required

example

Provide a method for reviewers to trigger the agent, such as a website where reviewers can invite and add phone numbers. 
If you need a list of phone numbers to add as test devices, contact rbm-support@vonage.com. 
Test the agent by sending a keyword like 'HELP' or 'START' to initiate conversation flow.

urls

array

media_type

string

Required

exampleimage

The media type of the agent preview.

Must be one of:imagevideo

url

string(uri)

examplehttps://www.example.com/rcs-agent-preview.jpg

The URL to the agent preview.

points_of_contact

array

Required

A list of points of contact for the RCS Agent.

first_name

string

Required

Max200

exampleJohn

The first name of the representative for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the representative for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the representative.

brand_website

string(uri)

examplehttps://www.example.com

The website URL of the brand represented by the RCS Agent.

job_title

string

Required

Max200

exampleTechnical Support

The job title of the point of contact.

traffic_estimates

object

Required

Traffic estimates for the RCS Agent.

average_global_traffic

string

Required

exampleTHOUSAND

Estimated global traffic.

Must be one of:THOUSANDTEN_THOUSANDFIFTY_THOUSANDHUNDRED_THOUSANDMILLIONMILLION_AND_MORE

average_message_rate_per_user

string

Required

exampleONCE_PER_MONTH

Estimated message rate per user.

Must be one of:ONCE_PER_MONTH2_4_TIMES_PER_MONTHONCE_PER_WEEK2_6_TIMES_PER_WEEKDAILYMULTIPLE_TIMES_PER_DAY

users_targeted

string

Required

exampleHUNDRED

Estimated number of users targeted.

Must be one of:HUNDREDTHOUSANDTEN_THOUSANDHUNDRED_THOUSANDHALF_MILLIONMILLIONMILLION_AND_MORE

user_experience

object

Required

interactions_description

string

Required

Max10000

example

This agent handles customer support inquiries and provides product information. Primary interactions include order status updates, account notifications, and FAQ responses. 
Secondary interactions may include promotional offers for existing customers and appointment scheduling assistance.

optin_description

string

Required

Max10000

example

This is a test environment. Customers consent to receive messages directly via request, phone, or email. 
Users can opt-in by visiting our website and providing their phone number, or by texting 'JOIN' to our SMS shortcode. 
Opt-in confirmation includes details about message frequency and content type.

Details how users will provide consent to receive messages from your RBM agent. This must clearly explain the opt-in mechanism and what users can expect when they subscribe to your messaging service.

optout_description

string

Required

Max10000

example

Customers can unsubscribe from receiving messages by replying 'STOP' to any message. 
They can also contact us by email at support@company.com. Users will receive a confirmation message when successfully unsubscribed, 
and can re-subscribe at any time by replying 'START'.

Explains how users can unsubscribe from receiving messages from your agent. Must describe the process for users to stop receiving communications and how your system handles these requests.

trigger_description

string

Required

Max10000

example

This account is used exclusively for sending test messages to introduce RCS capabilities to customers. 
Triggers include: order placement confirmations, shipping notifications, appointment reminders, customer service escalations, 
and weekly promotional campaigns for opted-in users.

Defines the external events or conditions that will cause your RBM agent to initiate conversations with users. These triggers determine when and why your agent sends the first message to users.

visual_design

object

brand_color

string

Required

example#8860CD

The hexadecimal color code for the primary color used in UI elements. The specified color must meet WCAG 2.1 contrast ratio of 4.5:1 for legibility.

array

Required

address

string

Required

examplesupport@example.com

The contact email address for the RCS Agent.

label

string

Max25

exampleCustomer Support

A label for the email address.

phone

array

Required

number

string(e164)

Required

example447700900001

E.164 formatted phone number without + prefix

label

string

Max25

exampleCustomer Support

A label for the phone number.

tagline

string

Required

Max100

exampleYour trusted partner in messaging.

A short phrase that represents the RCS Agent.

website

array

Required

url

string(uri)

Required

examplehttps://example.com

label

string

Max25

exampleCompany Website

A label for the website URL.

logo_image

string(uri)

Required

examplehttps://agent-logos.storage.googleapis.com/_/mbsy6ycz7BnqOi4WKZlOmpkz

image/png
image/jpeg
image/jpg

Any image file not meeting the requirements will result in an error response. The logo image is not modifiable after agent verification.

banner_image

string(uri)

Required

examplehttps://agent-logos.storage.googleapis.com/_/mbsy64um0BwndPRK8ECPyeqb

image/png
image/jpeg
image/jpg

Any image file not meeting the requirements will result in an error response. The banner image is not modifiable after agent verification.

privacy_policy

string(uri)

examplehttps://www.example.com/privacy-policy

The publicly accessible URL of the privacy policy for the RCS Agent.

terms_of_service

string(uri)

examplehttps://www.example.com/terms-of-service

The publicly accessible URL of the terms of service for the RCS Agent.

representative

object

first_name

string

Required

Max200

exampleJohn

The first name of the representative for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the representative for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the representative.

brand_website

string(uri)

examplehttps://www.example.com

The website URL of the brand represented by the RCS Agent.

created_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent was created.

updated_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent was last updated.

Example Response

Get Agent (Deprecated)

Retrieve an existing RCS Agent. Deprecated, please use the v2 endpoint instead.

gethttps://api.nexmo.com/v1/channel-manager/rcs/agents/:agent_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

agent_id

string

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

Agent ID

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the created RCS Agent.

state

string

exampleDRAFT

The current state of the created RCS Agent.

application_settings

object

application_id

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The id of the Vonage application with which to associate this agent.

basic_info

object

Required

brand_id

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the RCS Brand.

display_name

string

Required

exampleExample Co

The unique display name of the RCS Agent.

sender_id

string

Required

exampleExampleCo-RCSAgentv1-1

hosting_region

string

Required

exampleNORTH_AMERICA

The geographic location where your RCS business messaging service will be hosted and operated. This can affect data residency and compliance requirements.

Must be one of:NORTH_AMERICAEUROPEASIA_PACIFIC

agent_purpose

string

Required

exampleTRANSACTIONAL

Specifies the intended use of the RCS Agent. This cannot be changed after creation.

Must be one of:PROMOTIONALTRANSACTIONALOTPMULTI_USE

billing_category

string

Required

exampleCONVERSATIONAL

Specifies the billing category of the RCS Agent.

Must be one of:CONVERSATIONALNON_CONVERSATIONAL

notes

string

exampleThis agent is used for transactional messages only.

Additional notes or comments about the RCS Agent.

DEPRECATED This parameter is deprecated and will be removed in future. It can still be included in the request for backward compatibility, but it will not have any effect on the RCS Agent.

carrier_requirements

object

agent_preview

object

Required

agent_access_instructions

string

Required

example

Provide a method for reviewers to trigger the agent, such as a website where reviewers can invite and add phone numbers. 
If you need a list of phone numbers to add as test devices, contact rbm-support@vonage.com. 
Test the agent by sending a keyword like 'HELP' or 'START' to initiate conversation flow.

urls

array

media_type

string

Required

exampleimage

The media type of the agent preview.

Must be one of:imagevideo

url

string(uri)

examplehttps://www.example.com/rcs-agent-preview.jpg

The URL to the agent preview.

points_of_contact

array

Required

A list of points of contact for the RCS Agent.

first_name

string

Required

Max200

exampleJohn

The first name of the representative for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the representative for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the representative.

brand_website

string(uri)

examplehttps://www.example.com

The website URL of the brand represented by the RCS Agent.

job_title

string

Required

Max200

exampleTechnical Support

The job title of the point of contact.

traffic_estimates

object

Required

Traffic estimates for the RCS Agent.

average_global_traffic

string

Required

exampleTHOUSAND

Estimated global traffic.

Must be one of:THOUSANDTEN_THOUSANDFIFTY_THOUSANDHUNDRED_THOUSANDMILLIONMILLION_AND_MORE

average_message_rate_per_user

string

Required

exampleONCE_PER_MONTH

Estimated message rate per user.

Must be one of:ONCE_PER_MONTH2_4_TIMES_PER_MONTHONCE_PER_WEEK2_6_TIMES_PER_WEEKDAILYMULTIPLE_TIMES_PER_DAY

users_targeted

string

Required

exampleHUNDRED

Estimated number of users targeted.

Must be one of:HUNDREDTHOUSANDTEN_THOUSANDHUNDRED_THOUSANDHALF_MILLIONMILLIONMILLION_AND_MORE

user_experience

object

Required

interactions_description

string

Required

Max10000

example

This agent handles customer support inquiries and provides product information. Primary interactions include order status updates, account notifications, and FAQ responses. 
Secondary interactions may include promotional offers for existing customers and appointment scheduling assistance.

optin_description

string

Required

Max10000

example

This is a test environment. Customers consent to receive messages directly via request, phone, or email. 
Users can opt-in by visiting our website and providing their phone number, or by texting 'JOIN' to our SMS shortcode. 
Opt-in confirmation includes details about message frequency and content type.

Details how users will provide consent to receive messages from your RBM agent. This must clearly explain the opt-in mechanism and what users can expect when they subscribe to your messaging service.

optout_description

string

Required

Max10000

example

Customers can unsubscribe from receiving messages by replying 'STOP' to any message. 
They can also contact us by email at support@company.com. Users will receive a confirmation message when successfully unsubscribed, 
and can re-subscribe at any time by replying 'START'.

Explains how users can unsubscribe from receiving messages from your agent. Must describe the process for users to stop receiving communications and how your system handles these requests.

trigger_description

string

Required

Max10000

example

This account is used exclusively for sending test messages to introduce RCS capabilities to customers. 
Triggers include: order placement confirmations, shipping notifications, appointment reminders, customer service escalations, 
and weekly promotional campaigns for opted-in users.

Defines the external events or conditions that will cause your RBM agent to initiate conversations with users. These triggers determine when and why your agent sends the first message to users.

visual_design

object

brand_color

string

Required

example#8860CD

The hexadecimal color code for the primary color used in UI elements. The specified color must meet WCAG 2.1 contrast ratio of 4.5:1 for legibility.

array

Required

address

string

Required

examplesupport@example.com

The contact email address for the RCS Agent.

label

string

Max25

exampleCustomer Support

A label for the email address.

phone

array

Required

number

string(e164)

Required

example447700900001

E.164 formatted phone number without + prefix

label

string

Max25

exampleCustomer Support

A label for the phone number.

tagline

string

Required

Max100

exampleYour trusted partner in messaging.

A short phrase that represents the RCS Agent.

website

array

Required

url

string(uri)

Required

examplehttps://example.com

label

string

Max25

exampleCompany Website

A label for the website URL.

logo_image

string(uri)

Required

examplehttps://agent-logos.storage.googleapis.com/_/mbsy6ycz7BnqOi4WKZlOmpkz

image/png
image/jpeg
image/jpg

Any image file not meeting the requirements will result in an error response. The logo image is not modifiable after agent verification.

banner_image

string(uri)

Required

examplehttps://agent-logos.storage.googleapis.com/_/mbsy64um0BwndPRK8ECPyeqb

image/png
image/jpeg
image/jpg

Any image file not meeting the requirements will result in an error response. The banner image is not modifiable after agent verification.

privacy_policy

string(uri)

examplehttps://www.example.com/privacy-policy

The publicly accessible URL of the privacy policy for the RCS Agent.

terms_of_service

string(uri)

examplehttps://www.example.com/terms-of-service

The publicly accessible URL of the terms of service for the RCS Agent.

representative

object

first_name

string

Required

Max200

exampleJohn

The first name of the representative for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the representative for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the representative.

brand_website

string(uri)

examplehttps://www.example.com

The website URL of the brand represented by the RCS Agent.

created_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent was created.

updated_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent was last updated.

test_devices

array

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The id of the test device.

phone

string(e164)

Required

example447700900001

E.164 formatted phone number without + prefix

status

string

Required

exampleACCEPTED

The current status of the test device.

created_at

string

Required

example2023-01-01T12:00:00Z

The date and time when the test device was created.

carriers

object

string

Required

exampleatt-us

The id of the carrier.

launch_state

string

exampleLAUNCH_STATE_UNLAUNCHED

The launch state of the carrier.

verification_details

object

status

string

exampleVERIFICATION_STATE_UNVERIFIED

The verification status of the RCS Agent.

launch_submitted_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent launch was submitted.

Example Response

Update Agent (Deprecated)

Fully update an existing RCS Agent. Deprecated, please use the v2 endpoint instead.

puthttps://api.nexmo.com/v1/channel-manager/rcs/agents/:agent_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

agent_id

string

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

Agent ID

Request Body
Content Type
application/json

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the created RCS Agent.

state

string

exampleDRAFT

The current state of the created RCS Agent.

application_settings

object

application_id

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The id of the Vonage application with which to associate this agent.

basic_info

object

Required

brand_id

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the RCS Brand.

display_name

string

Required

exampleExample Co

The unique display name of the RCS Agent.

sender_id

string

Required

exampleExampleCo-RCSAgentv1-1

hosting_region

string

Required

exampleNORTH_AMERICA

The geographic location where your RCS business messaging service will be hosted and operated. This can affect data residency and compliance requirements.

Must be one of:NORTH_AMERICAEUROPEASIA_PACIFIC

agent_purpose

string

Required

exampleTRANSACTIONAL

Specifies the intended use of the RCS Agent. This cannot be changed after creation.

Must be one of:PROMOTIONALTRANSACTIONALOTPMULTI_USE

billing_category

string

Required

exampleCONVERSATIONAL

Specifies the billing category of the RCS Agent.

Must be one of:CONVERSATIONALNON_CONVERSATIONAL

notes

string

exampleThis agent is used for transactional messages only.

Additional notes or comments about the RCS Agent.

DEPRECATED This parameter is deprecated and will be removed in future. It can still be included in the request for backward compatibility, but it will not have any effect on the RCS Agent.

carrier_requirements

object

agent_preview

object

Required

agent_access_instructions

string

Required

example

Provide a method for reviewers to trigger the agent, such as a website where reviewers can invite and add phone numbers. 
If you need a list of phone numbers to add as test devices, contact rbm-support@vonage.com. 
Test the agent by sending a keyword like 'HELP' or 'START' to initiate conversation flow.

urls

array

media_type

string

Required

exampleimage

The media type of the agent preview.

Must be one of:imagevideo

url

string(uri)

examplehttps://www.example.com/rcs-agent-preview.jpg

The URL to the agent preview.

points_of_contact

array

Required

A list of points of contact for the RCS Agent.

first_name

string

Required

Max200

exampleJohn

The first name of the representative for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the representative for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the representative.

brand_website

string(uri)

examplehttps://www.example.com

The website URL of the brand represented by the RCS Agent.

job_title

string

Required

Max200

exampleTechnical Support

The job title of the point of contact.

traffic_estimates

object

Required

Traffic estimates for the RCS Agent.

average_global_traffic

string

Required

exampleTHOUSAND

Estimated global traffic.

Must be one of:THOUSANDTEN_THOUSANDFIFTY_THOUSANDHUNDRED_THOUSANDMILLIONMILLION_AND_MORE

average_message_rate_per_user

string

Required

exampleONCE_PER_MONTH

Estimated message rate per user.

Must be one of:ONCE_PER_MONTH2_4_TIMES_PER_MONTHONCE_PER_WEEK2_6_TIMES_PER_WEEKDAILYMULTIPLE_TIMES_PER_DAY

users_targeted

string

Required

exampleHUNDRED

Estimated number of users targeted.

Must be one of:HUNDREDTHOUSANDTEN_THOUSANDHUNDRED_THOUSANDHALF_MILLIONMILLIONMILLION_AND_MORE

user_experience

object

Required

interactions_description

string

Required

Max10000

example

This agent handles customer support inquiries and provides product information. Primary interactions include order status updates, account notifications, and FAQ responses. 
Secondary interactions may include promotional offers for existing customers and appointment scheduling assistance.

optin_description

string

Required

Max10000

example

This is a test environment. Customers consent to receive messages directly via request, phone, or email. 
Users can opt-in by visiting our website and providing their phone number, or by texting 'JOIN' to our SMS shortcode. 
Opt-in confirmation includes details about message frequency and content type.

Details how users will provide consent to receive messages from your RBM agent. This must clearly explain the opt-in mechanism and what users can expect when they subscribe to your messaging service.

optout_description

string

Required

Max10000

example

Customers can unsubscribe from receiving messages by replying 'STOP' to any message. 
They can also contact us by email at support@company.com. Users will receive a confirmation message when successfully unsubscribed, 
and can re-subscribe at any time by replying 'START'.

Explains how users can unsubscribe from receiving messages from your agent. Must describe the process for users to stop receiving communications and how your system handles these requests.

trigger_description

string

Required

Max10000

example

This account is used exclusively for sending test messages to introduce RCS capabilities to customers. 
Triggers include: order placement confirmations, shipping notifications, appointment reminders, customer service escalations, 
and weekly promotional campaigns for opted-in users.

Defines the external events or conditions that will cause your RBM agent to initiate conversations with users. These triggers determine when and why your agent sends the first message to users.

visual_design

object

brand_color

string

Required

example#8860CD

The hexadecimal color code for the primary color used in UI elements. The specified color must meet WCAG 2.1 contrast ratio of 4.5:1 for legibility.

array

Required

address

string

Required

examplesupport@example.com

The contact email address for the RCS Agent.

label

string

Max25

exampleCustomer Support

A label for the email address.

phone

array

Required

number

string(e164)

Required

example447700900001

E.164 formatted phone number without + prefix

label

string

Max25

exampleCustomer Support

A label for the phone number.

tagline

string

Required

Max100

exampleYour trusted partner in messaging.

A short phrase that represents the RCS Agent.

website

array

Required

url

string(uri)

Required

examplehttps://example.com

label

string

Max25

exampleCompany Website

A label for the website URL.

logo_image

string(uri)

Required

examplehttps://agent-logos.storage.googleapis.com/_/mbsy6ycz7BnqOi4WKZlOmpkz

image/png
image/jpeg
image/jpg

Any image file not meeting the requirements will result in an error response. The logo image is not modifiable after agent verification.

banner_image

string(uri)

Required

examplehttps://agent-logos.storage.googleapis.com/_/mbsy64um0BwndPRK8ECPyeqb

image/png
image/jpeg
image/jpg

Any image file not meeting the requirements will result in an error response. The banner image is not modifiable after agent verification.

privacy_policy

string(uri)

examplehttps://www.example.com/privacy-policy

The publicly accessible URL of the privacy policy for the RCS Agent.

terms_of_service

string(uri)

examplehttps://www.example.com/terms-of-service

The publicly accessible URL of the terms of service for the RCS Agent.

representative

object

first_name

string

Required

Max200

exampleJohn

The first name of the representative for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the representative for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the representative.

brand_website

string(uri)

examplehttps://www.example.com

The website URL of the brand represented by the RCS Agent.

created_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent was created.

updated_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent was last updated.

Example Request

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the created RCS Agent.

state

string

exampleDRAFT

The current state of the created RCS Agent.

application_settings

object

application_id

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The id of the Vonage application with which to associate this agent.

basic_info

object

Required

brand_id

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the RCS Brand.

display_name

string

Required

exampleExample Co

The unique display name of the RCS Agent.

sender_id

string

Required

exampleExampleCo-RCSAgentv1-1

hosting_region

string

Required

exampleNORTH_AMERICA

The geographic location where your RCS business messaging service will be hosted and operated. This can affect data residency and compliance requirements.

Must be one of:NORTH_AMERICAEUROPEASIA_PACIFIC

agent_purpose

string

Required

exampleTRANSACTIONAL

Specifies the intended use of the RCS Agent. This cannot be changed after creation.

Must be one of:PROMOTIONALTRANSACTIONALOTPMULTI_USE

billing_category

string

Required

exampleCONVERSATIONAL

Specifies the billing category of the RCS Agent.

Must be one of:CONVERSATIONALNON_CONVERSATIONAL

notes

string

exampleThis agent is used for transactional messages only.

Additional notes or comments about the RCS Agent.

DEPRECATED This parameter is deprecated and will be removed in future. It can still be included in the request for backward compatibility, but it will not have any effect on the RCS Agent.

carrier_requirements

object

agent_preview

object

Required

agent_access_instructions

string

Required

example

Provide a method for reviewers to trigger the agent, such as a website where reviewers can invite and add phone numbers. 
If you need a list of phone numbers to add as test devices, contact rbm-support@vonage.com. 
Test the agent by sending a keyword like 'HELP' or 'START' to initiate conversation flow.

urls

array

media_type

string

Required

exampleimage

The media type of the agent preview.

Must be one of:imagevideo

url

string(uri)

examplehttps://www.example.com/rcs-agent-preview.jpg

The URL to the agent preview.

points_of_contact

array

Required

A list of points of contact for the RCS Agent.

first_name

string

Required

Max200

exampleJohn

The first name of the representative for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the representative for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the representative.

brand_website

string(uri)

examplehttps://www.example.com

The website URL of the brand represented by the RCS Agent.

job_title

string

Required

Max200

exampleTechnical Support

The job title of the point of contact.

traffic_estimates

object

Required

Traffic estimates for the RCS Agent.

average_global_traffic

string

Required

exampleTHOUSAND

Estimated global traffic.

Must be one of:THOUSANDTEN_THOUSANDFIFTY_THOUSANDHUNDRED_THOUSANDMILLIONMILLION_AND_MORE

average_message_rate_per_user

string

Required

exampleONCE_PER_MONTH

Estimated message rate per user.

Must be one of:ONCE_PER_MONTH2_4_TIMES_PER_MONTHONCE_PER_WEEK2_6_TIMES_PER_WEEKDAILYMULTIPLE_TIMES_PER_DAY

users_targeted

string

Required

exampleHUNDRED

Estimated number of users targeted.

Must be one of:HUNDREDTHOUSANDTEN_THOUSANDHUNDRED_THOUSANDHALF_MILLIONMILLIONMILLION_AND_MORE

user_experience

object

Required

interactions_description

string

Required

Max10000

example

This agent handles customer support inquiries and provides product information. Primary interactions include order status updates, account notifications, and FAQ responses. 
Secondary interactions may include promotional offers for existing customers and appointment scheduling assistance.

optin_description

string

Required

Max10000

example

This is a test environment. Customers consent to receive messages directly via request, phone, or email. 
Users can opt-in by visiting our website and providing their phone number, or by texting 'JOIN' to our SMS shortcode. 
Opt-in confirmation includes details about message frequency and content type.

Details how users will provide consent to receive messages from your RBM agent. This must clearly explain the opt-in mechanism and what users can expect when they subscribe to your messaging service.

optout_description

string

Required

Max10000

example

Customers can unsubscribe from receiving messages by replying 'STOP' to any message. 
They can also contact us by email at support@company.com. Users will receive a confirmation message when successfully unsubscribed, 
and can re-subscribe at any time by replying 'START'.

Explains how users can unsubscribe from receiving messages from your agent. Must describe the process for users to stop receiving communications and how your system handles these requests.

trigger_description

string

Required

Max10000

example

This account is used exclusively for sending test messages to introduce RCS capabilities to customers. 
Triggers include: order placement confirmations, shipping notifications, appointment reminders, customer service escalations, 
and weekly promotional campaigns for opted-in users.

Defines the external events or conditions that will cause your RBM agent to initiate conversations with users. These triggers determine when and why your agent sends the first message to users.

visual_design

object

brand_color

string

Required

example#8860CD

The hexadecimal color code for the primary color used in UI elements. The specified color must meet WCAG 2.1 contrast ratio of 4.5:1 for legibility.

array

Required

address

string

Required

examplesupport@example.com

The contact email address for the RCS Agent.

label

string

Max25

exampleCustomer Support

A label for the email address.

phone

array

Required

number

string(e164)

Required

example447700900001

E.164 formatted phone number without + prefix

label

string

Max25

exampleCustomer Support

A label for the phone number.

tagline

string

Required

Max100

exampleYour trusted partner in messaging.

A short phrase that represents the RCS Agent.

website

array

Required

url

string(uri)

Required

examplehttps://example.com

label

string

Max25

exampleCompany Website

A label for the website URL.

logo_image

string(uri)

Required

examplehttps://agent-logos.storage.googleapis.com/_/mbsy6ycz7BnqOi4WKZlOmpkz

image/png
image/jpeg
image/jpg

Any image file not meeting the requirements will result in an error response. The logo image is not modifiable after agent verification.

banner_image

string(uri)

Required

examplehttps://agent-logos.storage.googleapis.com/_/mbsy64um0BwndPRK8ECPyeqb

image/png
image/jpeg
image/jpg

Any image file not meeting the requirements will result in an error response. The banner image is not modifiable after agent verification.

privacy_policy

string(uri)

examplehttps://www.example.com/privacy-policy

The publicly accessible URL of the privacy policy for the RCS Agent.

terms_of_service

string(uri)

examplehttps://www.example.com/terms-of-service

The publicly accessible URL of the terms of service for the RCS Agent.

representative

object

first_name

string

Required

Max200

exampleJohn

The first name of the representative for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the representative for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the representative.

brand_website

string(uri)

examplehttps://www.example.com

The website URL of the brand represented by the RCS Agent.

created_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent was created.

updated_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent was last updated.

test_devices

array

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The id of the test device.

phone

string(e164)

Required

example447700900001

E.164 formatted phone number without + prefix

status

string

Required

exampleACCEPTED

The current status of the test device.

created_at

string

Required

example2023-01-01T12:00:00Z

The date and time when the test device was created.

carriers

object

string

Required

exampleatt-us

The id of the carrier.

launch_state

string

exampleLAUNCH_STATE_UNLAUNCHED

The launch state of the carrier.

verification_details

object

status

string

exampleVERIFICATION_STATE_UNVERIFIED

The verification status of the RCS Agent.

launch_submitted_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent launch was submitted.

Example Response

Partially Update Agent (Deprecated)

Partially update an existing RCS Agent. Deprecated, please use the v2 endpoint instead.

patchhttps://api.nexmo.com/v1/channel-manager/rcs/agents/:agent_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

agent_id

string

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

Agent ID

Request Body
Content Type
application/json

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the created RCS Agent.

state

string

exampleDRAFT

The current state of the created RCS Agent.

application_settings

object

application_id

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The id of the Vonage application with which to associate this agent.

basic_info

object

Required

brand_id

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the RCS Brand.

display_name

string

Required

exampleExample Co

The unique display name of the RCS Agent.

sender_id

string

Required

exampleExampleCo-RCSAgentv1-1

hosting_region

string

Required

exampleNORTH_AMERICA

The geographic location where your RCS business messaging service will be hosted and operated. This can affect data residency and compliance requirements.

Must be one of:NORTH_AMERICAEUROPEASIA_PACIFIC

agent_purpose

string

Required

exampleTRANSACTIONAL

Specifies the intended use of the RCS Agent. This cannot be changed after creation.

Must be one of:PROMOTIONALTRANSACTIONALOTPMULTI_USE

billing_category

string

Required

exampleCONVERSATIONAL

Specifies the billing category of the RCS Agent.

Must be one of:CONVERSATIONALNON_CONVERSATIONAL

notes

string

exampleThis agent is used for transactional messages only.

Additional notes or comments about the RCS Agent.

DEPRECATED This parameter is deprecated and will be removed in future. It can still be included in the request for backward compatibility, but it will not have any effect on the RCS Agent.

carrier_requirements

object

agent_preview

object

Required

agent_access_instructions

string

Required

example

Provide a method for reviewers to trigger the agent, such as a website where reviewers can invite and add phone numbers. 
If you need a list of phone numbers to add as test devices, contact rbm-support@vonage.com. 
Test the agent by sending a keyword like 'HELP' or 'START' to initiate conversation flow.

urls

array

media_type

string

Required

exampleimage

The media type of the agent preview.

Must be one of:imagevideo

url

string(uri)

examplehttps://www.example.com/rcs-agent-preview.jpg

The URL to the agent preview.

points_of_contact

array

Required

A list of points of contact for the RCS Agent.

first_name

string

Required

Max200

exampleJohn

The first name of the representative for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the representative for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the representative.

brand_website

string(uri)

examplehttps://www.example.com

The website URL of the brand represented by the RCS Agent.

job_title

string

Required

Max200

exampleTechnical Support

The job title of the point of contact.

traffic_estimates

object

Required

Traffic estimates for the RCS Agent.

average_global_traffic

string

Required

exampleTHOUSAND

Estimated global traffic.

Must be one of:THOUSANDTEN_THOUSANDFIFTY_THOUSANDHUNDRED_THOUSANDMILLIONMILLION_AND_MORE

average_message_rate_per_user

string

Required

exampleONCE_PER_MONTH

Estimated message rate per user.

Must be one of:ONCE_PER_MONTH2_4_TIMES_PER_MONTHONCE_PER_WEEK2_6_TIMES_PER_WEEKDAILYMULTIPLE_TIMES_PER_DAY

users_targeted

string

Required

exampleHUNDRED

Estimated number of users targeted.

Must be one of:HUNDREDTHOUSANDTEN_THOUSANDHUNDRED_THOUSANDHALF_MILLIONMILLIONMILLION_AND_MORE

user_experience

object

Required

interactions_description

string

Required

Max10000

example

This agent handles customer support inquiries and provides product information. Primary interactions include order status updates, account notifications, and FAQ responses. 
Secondary interactions may include promotional offers for existing customers and appointment scheduling assistance.

optin_description

string

Required

Max10000

example

This is a test environment. Customers consent to receive messages directly via request, phone, or email. 
Users can opt-in by visiting our website and providing their phone number, or by texting 'JOIN' to our SMS shortcode. 
Opt-in confirmation includes details about message frequency and content type.

Details how users will provide consent to receive messages from your RBM agent. This must clearly explain the opt-in mechanism and what users can expect when they subscribe to your messaging service.

optout_description

string

Required

Max10000

example

Customers can unsubscribe from receiving messages by replying 'STOP' to any message. 
They can also contact us by email at support@company.com. Users will receive a confirmation message when successfully unsubscribed, 
and can re-subscribe at any time by replying 'START'.

Explains how users can unsubscribe from receiving messages from your agent. Must describe the process for users to stop receiving communications and how your system handles these requests.

trigger_description

string

Required

Max10000

example

This account is used exclusively for sending test messages to introduce RCS capabilities to customers. 
Triggers include: order placement confirmations, shipping notifications, appointment reminders, customer service escalations, 
and weekly promotional campaigns for opted-in users.

Defines the external events or conditions that will cause your RBM agent to initiate conversations with users. These triggers determine when and why your agent sends the first message to users.

visual_design

object

brand_color

string

Required

example#8860CD

The hexadecimal color code for the primary color used in UI elements. The specified color must meet WCAG 2.1 contrast ratio of 4.5:1 for legibility.

array

Required

address

string

Required

examplesupport@example.com

The contact email address for the RCS Agent.

label

string

Max25

exampleCustomer Support

A label for the email address.

phone

array

Required

number

string(e164)

Required

example447700900001

E.164 formatted phone number without + prefix

label

string

Max25

exampleCustomer Support

A label for the phone number.

tagline

string

Required

Max100

exampleYour trusted partner in messaging.

A short phrase that represents the RCS Agent.

website

array

Required

url

string(uri)

Required

examplehttps://example.com

label

string

Max25

exampleCompany Website

A label for the website URL.

logo_image

string(uri)

Required

examplehttps://agent-logos.storage.googleapis.com/_/mbsy6ycz7BnqOi4WKZlOmpkz

image/png
image/jpeg
image/jpg

Any image file not meeting the requirements will result in an error response. The logo image is not modifiable after agent verification.

banner_image

string(uri)

Required

examplehttps://agent-logos.storage.googleapis.com/_/mbsy64um0BwndPRK8ECPyeqb

image/png
image/jpeg
image/jpg

Any image file not meeting the requirements will result in an error response. The banner image is not modifiable after agent verification.

privacy_policy

string(uri)

examplehttps://www.example.com/privacy-policy

The publicly accessible URL of the privacy policy for the RCS Agent.

terms_of_service

string(uri)

examplehttps://www.example.com/terms-of-service

The publicly accessible URL of the terms of service for the RCS Agent.

representative

object

first_name

string

Required

Max200

exampleJohn

The first name of the representative for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the representative for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the representative.

brand_website

string(uri)

examplehttps://www.example.com

The website URL of the brand represented by the RCS Agent.

created_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent was created.

updated_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent was last updated.

Example Request

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the created RCS Agent.

state

string

exampleDRAFT

The current state of the created RCS Agent.

application_settings

object

application_id

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The id of the Vonage application with which to associate this agent.

basic_info

object

Required

brand_id

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the RCS Brand.

display_name

string

Required

exampleExample Co

The unique display name of the RCS Agent.

sender_id

string

Required

exampleExampleCo-RCSAgentv1-1

hosting_region

string

Required

exampleNORTH_AMERICA

The geographic location where your RCS business messaging service will be hosted and operated. This can affect data residency and compliance requirements.

Must be one of:NORTH_AMERICAEUROPEASIA_PACIFIC

agent_purpose

string

Required

exampleTRANSACTIONAL

Specifies the intended use of the RCS Agent. This cannot be changed after creation.

Must be one of:PROMOTIONALTRANSACTIONALOTPMULTI_USE

billing_category

string

Required

exampleCONVERSATIONAL

Specifies the billing category of the RCS Agent.

Must be one of:CONVERSATIONALNON_CONVERSATIONAL

notes

string

exampleThis agent is used for transactional messages only.

Additional notes or comments about the RCS Agent.

DEPRECATED This parameter is deprecated and will be removed in future. It can still be included in the request for backward compatibility, but it will not have any effect on the RCS Agent.

carrier_requirements

object

agent_preview

object

Required

agent_access_instructions

string

Required

example

Provide a method for reviewers to trigger the agent, such as a website where reviewers can invite and add phone numbers. 
If you need a list of phone numbers to add as test devices, contact rbm-support@vonage.com. 
Test the agent by sending a keyword like 'HELP' or 'START' to initiate conversation flow.

urls

array

media_type

string

Required

exampleimage

The media type of the agent preview.

Must be one of:imagevideo

url

string(uri)

examplehttps://www.example.com/rcs-agent-preview.jpg

The URL to the agent preview.

points_of_contact

array

Required

A list of points of contact for the RCS Agent.

first_name

string

Required

Max200

exampleJohn

The first name of the representative for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the representative for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the representative.

brand_website

string(uri)

examplehttps://www.example.com

The website URL of the brand represented by the RCS Agent.

job_title

string

Required

Max200

exampleTechnical Support

The job title of the point of contact.

traffic_estimates

object

Required

Traffic estimates for the RCS Agent.

average_global_traffic

string

Required

exampleTHOUSAND

Estimated global traffic.

Must be one of:THOUSANDTEN_THOUSANDFIFTY_THOUSANDHUNDRED_THOUSANDMILLIONMILLION_AND_MORE

average_message_rate_per_user

string

Required

exampleONCE_PER_MONTH

Estimated message rate per user.

Must be one of:ONCE_PER_MONTH2_4_TIMES_PER_MONTHONCE_PER_WEEK2_6_TIMES_PER_WEEKDAILYMULTIPLE_TIMES_PER_DAY

users_targeted

string

Required

exampleHUNDRED

Estimated number of users targeted.

Must be one of:HUNDREDTHOUSANDTEN_THOUSANDHUNDRED_THOUSANDHALF_MILLIONMILLIONMILLION_AND_MORE

user_experience

object

Required

interactions_description

string

Required

Max10000

example

This agent handles customer support inquiries and provides product information. Primary interactions include order status updates, account notifications, and FAQ responses. 
Secondary interactions may include promotional offers for existing customers and appointment scheduling assistance.

optin_description

string

Required

Max10000

example

This is a test environment. Customers consent to receive messages directly via request, phone, or email. 
Users can opt-in by visiting our website and providing their phone number, or by texting 'JOIN' to our SMS shortcode. 
Opt-in confirmation includes details about message frequency and content type.

Details how users will provide consent to receive messages from your RBM agent. This must clearly explain the opt-in mechanism and what users can expect when they subscribe to your messaging service.

optout_description

string

Required

Max10000

example

Customers can unsubscribe from receiving messages by replying 'STOP' to any message. 
They can also contact us by email at support@company.com. Users will receive a confirmation message when successfully unsubscribed, 
and can re-subscribe at any time by replying 'START'.

Explains how users can unsubscribe from receiving messages from your agent. Must describe the process for users to stop receiving communications and how your system handles these requests.

trigger_description

string

Required

Max10000

example

This account is used exclusively for sending test messages to introduce RCS capabilities to customers. 
Triggers include: order placement confirmations, shipping notifications, appointment reminders, customer service escalations, 
and weekly promotional campaigns for opted-in users.

Defines the external events or conditions that will cause your RBM agent to initiate conversations with users. These triggers determine when and why your agent sends the first message to users.

visual_design

object

brand_color

string

Required

example#8860CD

The hexadecimal color code for the primary color used in UI elements. The specified color must meet WCAG 2.1 contrast ratio of 4.5:1 for legibility.

array

Required

address

string

Required

examplesupport@example.com

The contact email address for the RCS Agent.

label

string

Max25

exampleCustomer Support

A label for the email address.

phone

array

Required

number

string(e164)

Required

example447700900001

E.164 formatted phone number without + prefix

label

string

Max25

exampleCustomer Support

A label for the phone number.

tagline

string

Required

Max100

exampleYour trusted partner in messaging.

A short phrase that represents the RCS Agent.

website

array

Required

url

string(uri)

Required

examplehttps://example.com

label

string

Max25

exampleCompany Website

A label for the website URL.

logo_image

string(uri)

Required

examplehttps://agent-logos.storage.googleapis.com/_/mbsy6ycz7BnqOi4WKZlOmpkz

image/png
image/jpeg
image/jpg

Any image file not meeting the requirements will result in an error response. The logo image is not modifiable after agent verification.

banner_image

string(uri)

Required

examplehttps://agent-logos.storage.googleapis.com/_/mbsy64um0BwndPRK8ECPyeqb

image/png
image/jpeg
image/jpg

Any image file not meeting the requirements will result in an error response. The banner image is not modifiable after agent verification.

privacy_policy

string(uri)

examplehttps://www.example.com/privacy-policy

The publicly accessible URL of the privacy policy for the RCS Agent.

terms_of_service

string(uri)

examplehttps://www.example.com/terms-of-service

The publicly accessible URL of the terms of service for the RCS Agent.

representative

object

first_name

string

Required

Max200

exampleJohn

The first name of the representative for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the representative for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the representative.

brand_website

string(uri)

examplehttps://www.example.com

The website URL of the brand represented by the RCS Agent.

created_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent was created.

updated_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent was last updated.

test_devices

array

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The id of the test device.

phone

string(e164)

Required

example447700900001

E.164 formatted phone number without + prefix

status

string

Required

exampleACCEPTED

The current status of the test device.

created_at

string

Required

example2023-01-01T12:00:00Z

The date and time when the test device was created.

carriers

object

string

Required

exampleatt-us

The id of the carrier.

launch_state

string

exampleLAUNCH_STATE_UNLAUNCHED

The launch state of the carrier.

verification_details

object

status

string

exampleVERIFICATION_STATE_UNVERIFIED

The verification status of the RCS Agent.

launch_submitted_at

string

example2023-01-01T12:00:00Z

The date and time when the RCS Agent launch was submitted.

Example Response

Get Carriers (Deprecated)

Retrieve a list of available carriers for RCS. Deprecated, please use the v2 endpoint instead.

gethttps://api.nexmo.com/v1/channel-manager/rcs/metadata/carriers

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

carriers

array

Required

A list of available carriers for RCS.

string

exampleverizon-us

A unique identifier for the carrier.

carrier

string

exampleVerizon

The name of the carrier.

country_letter_code

string

exampleUS

Code for the country where the carrier operates.

Example Response

Add Carriers to Agent (Deprecated)

Add carriers to an existing RCS Agent. Deprecated, please use the v2 endpoint instead.

posthttps://api.nexmo.com/v1/channel-manager/rcs/agents/:agent_id/carriers

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

agent_id

string

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

Agent ID

Request Body
Content Type
application/json

carriers

array

Required

An array of Carrier IDs to add to the RCS Agent.

Example Request

Responses
Content Type
application/json

Accepted

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

message

string

Required

exampleCarriers accepted for processing

Example Response

Add Test Devices to Agent (Deprecated)

Add test devices to an existing RCS Agent. Deprecated, please use the v2 endpoint instead.

posthttps://api.nexmo.com/v1/channel-manager/rcs/agents/:agent_id/test-devices

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

agent_id

string

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

Agent ID

Request Body
Content Type
application/json

phone

string

Required

example+14155552671

The phone number to add to the RCS Agent in E.164 format.

Example Request

Responses
Content Type
application/json

Accepted

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string(uuid)

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The unique ID of the created test device.

phone

string(e164)

Required

example447700900001

E.164 formatted phone number without + prefix

created_at

string

Required

example2023-01-01T12:00:00Z

The date and time when the test device was created.

status

string

Required

exampleACCEPTED

The current status of the test device.

Example Response

Remove Test Device from Agent (Deprecated)

Remove a test device from an existing RCS Agent. Deprecated, please use the v2 endpoint instead.

deletehttps://api.nexmo.com/v1/channel-manager/rcs/agents/:agent_id/test-devices/:test_device_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

agent_id

string

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

Agent ID

test_device_id

string

Required

example019809ba-a274-7bd2-aea0-f1f70f2210dc

Test Device Id

Responses

No Content - Resource successfully deleted

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

List Agents

Retrieve a list of RCS Agents.

gethttps://api.nexmo.com/v2/channel-manager/rcs/agents

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Query Parameters

brand_id

string(uuid)

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

The id of an RCS Brand to filter by.

state

string

exampleDRAFT

The state of the RCS Agent to filter by. Can be specified multiple times for multiple values.

Must be one of:DRAFTCREATEDPENDINGLAUNCHEDREJECTEDUNLAUNCHED

agent_purpose

string

exampleTRANSACTIONAL

The agent_purpose of the RCS Agent to filter by. Can be specified multiple times.

Must be one of:PROMOTIONALTRANSACTIONALOTPMULTI_USE

billing_category

string

exampleCONVERSATIONAL

The billing_category of the RCS Agent to filter by. Can be specified multiple times.

Must be one of:SINGLE_MESSAGEBASIC_MESSAGECONVERSATIONALNON_CONVERSATIONAL

hosting_region

string

exampleNORTH_AMERICA

The hosting_region of the RCS Agent to filter by. Can be specified multiple times.

Must be one of:NORTH_AMERICAEUROPEASIA_PACIFIC

page

integer

Min1

Default1

example1

Page number to retrieve

page_size

integer

Min1

Default10

example20

Number of items to return per page

order

string

The order.

Must be one of:ascdesc

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

page

integer

Required

Min1

Default1

example1

The current page

page_size

integer

Required

Min1

Default10

example20

The size of the page

total_items

integer

Required

example871

The total number of items in the resource list

total_pages

integer

Required

Min1

example42

Total number of pages

_embedded

object

Required

agents

array

Required

A list of RCS Agents.

string(uuid)

Required

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Unique agent identifier

state

string

exampleDRAFT

Current state of the agent

Must be one of:DRAFTCREATEDPENDINGLAUNCHEDREJECTEDUNLAUNCHED

basic_info

object

Required

display_name

string

Required

Max40

exampleAcme Bank

Display name of the RCS agent shown to end users

sender_id

string

Required

Max50

exampleacme-bank

Unique sender identifier for the agent

hosting_region

string

Required

exampleEUROPE

Region where the agent is hosted

Must be one of:NORTH_AMERICAEUROPEASIA_PACIFIC

agent_purpose

string

Required

exampleTRANSACTIONAL

Intended use case of the agent

Must be one of:TRANSACTIONALPROMOTIONALOTPMULTI_USE

billing_category

string

Required

exampleCONVERSATIONAL

Billing category determining how messages are charged

Must be one of:BASIC_MESSAGESINGLE_MESSAGECONVERSATIONALNON_CONVERSATIONAL

brand_id

string(uuid)

Required

Max100

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Identifier of the brand this agent belongs to

account_manager_email

string

examplemanager@vonage.com

Vonage account manager email address

reseller_email

string

examplereseller@partner.com

Reseller email address, in case the agent is created by a reseller party

visual_design

object

tagline

string

Required

Max100

exampleYour trusted banking assistant

Short tagline describing the agent or brand

brand_color

string

Required

example#FF5733

Brand color in hex format, used for button text and UI elements above the agent phone number. Must meet a minimum contrast ratio of 4.5:1 against white (WCAG 2.0). See the support article

logo_image

string

examplehttps://cdn.example.com/logo.png

URL of the agent logo image. Shown as a circular avatar next to messages. Requirements: JPEG or PNG, 224x224 px, max 50 KB. See the support article

banner_image

string

examplehttps://cdn.example.com/banner.png

URL of the agent banner image. Displayed as a header when users view the agent business info. Requirements: JPEG, 1440x448 px, max 200 KB. See the support article

phone

array

Required

List of phone contact numbers (1-3)

number

string

Required

example+12025551234

Phone number in E.164 format

label

string

Max25

exampleCustomer Support

Display label for this phone number

array

Required

List of email contact addresses (1-3)

address

string

Required

Min1

examplesupport@example.com

Email address

label

string

Max25

exampleCustomer Support

Display label for this email address

website

array

Required

List of website links (1-3)

url

string

Required

examplehttps://www.example.com

Website URL

label

string

Max25

exampleOfficial Website

Display label for this website

privacy_policy

string

examplehttps://www.example.com/privacy

URL of the privacy policy

terms_of_service

string

examplehttps://www.example.com/terms

URL of the terms of service

application_settings

object

application_id

string

Required

examplea1b2c3d4-e5f6-7890-abcd-ef1234567890

Vonage application ID to associate with this agent

test_devices

array

string(uuid)

Required

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Unique test device identifier

phone

string

Required

example+12025551234

Phone number of the test device in E.164 format

created_at

string

Required

Date and time when the test device was added

status

string

Required

exampleACTIVE

Status of the test device registration

representative

object

first_name

string

Required

Max200

exampleJane

First name of the authorized representative

last_name

string

Required

Max200

exampleDoe

Last name of the authorized representative

title

string

Max200

exampleHead of Messaging

Job title of the authorized representative

string

Required

examplejane.doe@example.com

Email address of the authorized representative

brand_website

string

examplehttps://www.example.com

Brand website URL

phone

string

example+12025551234

Phone number in E.164 format

carrier_requirements

object

version

string

Required

examplev2

Carrier requirements schema version

points_of_contact

array

first_name

string

Required

Max200

exampleJohn

The first name of the point of contact for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the point of contact for the RCS Agent.

job_title

string

Required

Max200

exampleHead of Messaging

The job title of the point of contact for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the point of contact for the RCS Agent.

phone

string

example+12025551234

The phone number of the point of contact for the RCS Agent.

agent_preview

object

Required

agent_access_instructions

string

Required

Max10000

exampleVisit https://example.com/rcs-agent and follow the onboarding flow.

Instructions for reviewers on how to access and test the agent

urls

array

List of media URLs showcasing the agent (up to 10)

media_type

string

Required

exampleimage

Media type of the preview asset

Must be one of:imagevideo

url

string

Required

examplehttps://cdn.example.com/preview.png

URL of the preview asset

rcs_agent_discovery_methods

object

selection

array

Required

Methods through which users discover the RCS agent

other_input

string

Max500

examplePromoted via in-store QR codes

Additional details when OTHER is selected

consent_management

object

Required

user_messaging_consent_methods

object

Required

selection

array

Required

Selected consent methods

other_input

string

Max500

exampleUsers consent via in-store sign-up forms

Additional details when OTHER is selected

users_opt_in_process

object

Required

selection

array

Required

Selected opt-in methods

links

array

URLs where users can opt in (up to 10)

first_opt_in_message

string

Required

Max1000

exampleWelcome! You have successfully opted in to receive updates from Acme Bank.

The first message sent to users after opting in

users_opt_out_methods

object

Required

selection

array

Required

Selected opt-out methods

other_input

string

Max500

exampleUsers can opt out via the account settings page

Additional details when OTHER is selected

opt_out_processing_time

object

Required

selection

string

Required

exampleWITHIN_5_MINUTES

How quickly opt-out requests are processed

Must be one of:WITHIN_5_MINUTESWITHIN_24_HOURSOTHER

other_input

string

Max500

exampleProcessed within 2 business days

Additional details when OTHER is selected

opt_out_confirmation_message

object

Required

selection

string

Required

exampleSUCCESSFULLY_UNSUBSCRIBED

Confirmation message template sent after opt-out

Must be one of:SUCCESSFULLY_UNSUBSCRIBEDWONT_RECEIVE_FURTHER_MESSAGESOPT_OUT_REQUEST_PROCESSEDREPLY_START_TO_RESUBSCRIBEOPT_OUT_CONFIRMEDOTHER

other_input

string

Max500

exampleYou have been unsubscribed. Contact support@example.com to resubscribe.

Additional details when OTHER is selected

cta_language

string

Min1

Max2000

exampleReply YES to receive exclusive offers from Acme Bank.

Call-to-action language used in consent flows

engagement_flows

object

Required

agent_description

string

Required

Max5000

exampleAcme Bank RCS agent helps customers check balances, receive transaction alerts, and manage payments.

Description of what the agent does and how it engages with users

reasons_messages_sent

object

Required

Reasons why messages are sent to users

selection

array

Required

Selected reasons for sending messages

other_input

string

Max500

exampleSending loyalty program milestone notifications

Additional details when OTHER is selected

monthly_user_message_count

string

Required

exampleTHREE_FIVE_MESSAGES

Estimated number of messages sent to each user per month

Must be one of:ONE_TWO_MESSAGESTHREE_FIVE_MESSAGESSIX_TEN_MESSAGESELEVEN_TWENTY_MESSAGESMORE_THAN_TWENTY_ONE_MESSAGES

rcs_user_interaction_types

object

Required

Types of interactions users have with the agent

selection

array

Required

Selected types of RCS user interactions

other_input

string

Max500

exampleUsers interact via custom carousels

Additional details when OTHER is selected

help_interaction

string

Min1

Max2000

exampleReply HELP for assistance or visit https://www.example.com/support

How the agent responds to HELP messages from users

message_samples

array

Sample messages the agent will send to users (3-10 samples required)

message_type

string

exampleRICH_MEDIA

Type of RCS messages the agent sends. Use RICH_TEXT or RICH_MEDIA for US carriers; BASIC or SINGLE for non-US carriers.

Must be one of:RICH_TEXTRICH_MEDIABASICSINGLE

agent_summary

object

program_summary

string

Min1

Max2000

exampleAcme Bank sends transactional alerts and OTP messages to account holders who have opted in.

Summary of the agent messaging program and its intended use

current_traffic

object

organic_website_traffic

object

Current organic website traffic range

min

integer(int64)

max

integer(int64)

existing_shortcode_traffic

boolean

exampletrue

Whether the brand currently uses a shortcode for messaging

shortcode_monthly_traffic

object

Monthly traffic volume range for the existing shortcode

min

integer(int64)

max

integer(int64)

shortcode

string

Max50

example12345

Existing shortcode number

carriers

array

string

Required

examplegoogle-us-att

Carrier identifier

launch_state

string

Current launch state for this carrier

update_time

string

Date and time of the last status update

launch_submitted_at

string

Date and time when the launch was submitted for this carrier

comment

string

Comment or reason associated with the current launch state

verification_details

object

status

string

exampleVERIFICATION_STATE_VERIFIED

Verification status of the agent

Must be one of:VERIFICATION_STATE_UNSPECIFIEDVERIFICATION_STATE_UNVERIFIEDVERIFICATION_STATE_PENDINGVERIFICATION_STATE_VERIFIED

brand_details

object

organization_name

string

Required

Max255

legal_form

string

Required

Max50

stock_symbol

string

Max12

legal_entity_type

string

Required

Max50

country_of_registration

string

Required

Min2

Max2

federal_tax_id

string

Max50

business_website_url

string

Required

Max255

address_line1

string

Required

Max255

address_line2

string

Max255

city

string

Required

Max100

state_or_province

string

Required

Max100

zip_or_post_code

string

Required

Max15

launch_submitted_at

string

Date and time when the agent launch was submitted

created_at

string

Date and time when the agent was created

updated_at

string

Date and time when the agent was last updated

_links

object

Required

HAL links for page-based paginated collections

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

first

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

object

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

object

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

last

object

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

Create Agent

Create a new RCS Agent.

posthttps://api.nexmo.com/v2/channel-manager/rcs/agents

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Request Body
Content Type
application/json

basic_info

object

Required

display_name

string

Required

Max40

exampleAcme Bank

Display name of the RCS agent shown to end users

sender_id

string

Required

Max50

exampleacme-bank

Unique sender identifier for the agent

hosting_region

string

Required

exampleEUROPE

Region where the agent is hosted

Must be one of:NORTH_AMERICAEUROPEASIA_PACIFIC

agent_purpose

string

Required

exampleTRANSACTIONAL

Intended use case of the agent

Must be one of:TRANSACTIONALPROMOTIONALOTPMULTI_USE

billing_category

string

Required

exampleCONVERSATIONAL

Billing category determining how messages are charged

Must be one of:BASIC_MESSAGESINGLE_MESSAGECONVERSATIONALNON_CONVERSATIONAL

brand_id

string(uuid)

Required

Max100

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Identifier of the brand this agent belongs to

account_manager_email

string

examplemanager@vonage.com

Vonage account manager email address

reseller_email

string

examplereseller@partner.com

Reseller email address, in case the agent is created by a reseller party

visual_design

object

Required

tagline

string

Required

Max100

exampleYour trusted banking assistant

Short tagline describing the agent or brand

brand_color

string

Required

example#FF5733

Brand color in hex format, used for button text and UI elements above the agent phone number. Must meet a minimum contrast ratio of 4.5:1 against white (WCAG 2.0). See the support article

logo_image

string

examplehttps://cdn.example.com/logo.png

URL of the agent logo image. Shown as a circular avatar next to messages. Requirements: JPEG or PNG, 224x224 px, max 50 KB. See the support article

banner_image

string

examplehttps://cdn.example.com/banner.png

URL of the agent banner image. Displayed as a header when users view the agent business info. Requirements: JPEG, 1440x448 px, max 200 KB. See the support article

phone

array

Required

List of phone contact numbers (1-3)

number

string

Required

example+12025551234

Phone number in E.164 format

label

string

Max25

exampleCustomer Support

Display label for this phone number

array

Required

List of email contact addresses (1-3)

address

string

Required

Min1

examplesupport@example.com

Email address

label

string

Max25

exampleCustomer Support

Display label for this email address

website

array

Required

List of website links (1-3)

url

string

Required

examplehttps://www.example.com

Website URL

label

string

Max25

exampleOfficial Website

Display label for this website

privacy_policy

string

examplehttps://www.example.com/privacy

URL of the privacy policy

terms_of_service

string

examplehttps://www.example.com/terms

URL of the terms of service

application_settings

object

Required

application_id

string

Required

examplea1b2c3d4-e5f6-7890-abcd-ef1234567890

Vonage application ID to associate with this agent

representative

object

first_name

string

Required

Max200

exampleJane

First name of the authorized representative

last_name

string

Required

Max200

exampleDoe

Last name of the authorized representative

title

string

Max200

exampleHead of Messaging

Job title of the authorized representative

string

Required

examplejane.doe@example.com

Email address of the authorized representative

brand_website

string

examplehttps://www.example.com

Brand website URL

phone

string

example+12025551234

Phone number in E.164 format

carrier_requirements

object

version

string

Required

examplev2

Carrier requirements schema version

points_of_contact

array

first_name

string

Required

Max200

exampleJohn

The first name of the point of contact for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the point of contact for the RCS Agent.

job_title

string

Required

Max200

exampleHead of Messaging

The job title of the point of contact for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the point of contact for the RCS Agent.

phone

string

example+12025551234

The phone number of the point of contact for the RCS Agent.

agent_preview

object

Required

agent_access_instructions

string

Required

Max10000

exampleVisit https://example.com/rcs-agent and follow the onboarding flow.

Instructions for reviewers on how to access and test the agent

urls

array

List of media URLs showcasing the agent (up to 10)

media_type

string

Required

exampleimage

Media type of the preview asset

Must be one of:imagevideo

url

string

Required

examplehttps://cdn.example.com/preview.png

URL of the preview asset

rcs_agent_discovery_methods

object

selection

array

Required

Methods through which users discover the RCS agent

other_input

string

Max500

examplePromoted via in-store QR codes

Additional details when OTHER is selected

consent_management

object

Required

user_messaging_consent_methods

object

Required

selection

array

Required

Selected consent methods

other_input

string

Max500

exampleUsers consent via in-store sign-up forms

Additional details when OTHER is selected

users_opt_in_process

object

Required

selection

array

Required

Selected opt-in methods

links

array

URLs where users can opt in (up to 10)

first_opt_in_message

string

Required

Max1000

exampleWelcome! You have successfully opted in to receive updates from Acme Bank.

The first message sent to users after opting in

users_opt_out_methods

object

Required

selection

array

Required

Selected opt-out methods

other_input

string

Max500

exampleUsers can opt out via the account settings page

Additional details when OTHER is selected

opt_out_processing_time

object

Required

selection

string

Required

exampleWITHIN_5_MINUTES

How quickly opt-out requests are processed

Must be one of:WITHIN_5_MINUTESWITHIN_24_HOURSOTHER

other_input

string

Max500

exampleProcessed within 2 business days

Additional details when OTHER is selected

opt_out_confirmation_message

object

Required

selection

string

Required

exampleSUCCESSFULLY_UNSUBSCRIBED

Confirmation message template sent after opt-out

Must be one of:SUCCESSFULLY_UNSUBSCRIBEDWONT_RECEIVE_FURTHER_MESSAGESOPT_OUT_REQUEST_PROCESSEDREPLY_START_TO_RESUBSCRIBEOPT_OUT_CONFIRMEDOTHER

other_input

string

Max500

exampleYou have been unsubscribed. Contact support@example.com to resubscribe.

Additional details when OTHER is selected

cta_language

string

Min1

Max2000

exampleReply YES to receive exclusive offers from Acme Bank.

Call-to-action language used in consent flows

engagement_flows

object

Required

agent_description

string

Required

Max5000

exampleAcme Bank RCS agent helps customers check balances, receive transaction alerts, and manage payments.

Description of what the agent does and how it engages with users

reasons_messages_sent

object

Required

Reasons why messages are sent to users

selection

array

Required

Selected reasons for sending messages

other_input

string

Max500

exampleSending loyalty program milestone notifications

Additional details when OTHER is selected

monthly_user_message_count

string

Required

exampleTHREE_FIVE_MESSAGES

Estimated number of messages sent to each user per month

Must be one of:ONE_TWO_MESSAGESTHREE_FIVE_MESSAGESSIX_TEN_MESSAGESELEVEN_TWENTY_MESSAGESMORE_THAN_TWENTY_ONE_MESSAGES

rcs_user_interaction_types

object

Required

Types of interactions users have with the agent

selection

array

Required

Selected types of RCS user interactions

other_input

string

Max500

exampleUsers interact via custom carousels

Additional details when OTHER is selected

help_interaction

string

Min1

Max2000

exampleReply HELP for assistance or visit https://www.example.com/support

How the agent responds to HELP messages from users

message_samples

array

Sample messages the agent will send to users (3-10 samples required)

message_type

string

exampleRICH_MEDIA

Type of RCS messages the agent sends. Use RICH_TEXT or RICH_MEDIA for US carriers; BASIC or SINGLE for non-US carriers.

Must be one of:RICH_TEXTRICH_MEDIABASICSINGLE

agent_summary

object

program_summary

string

Min1

Max2000

exampleAcme Bank sends transactional alerts and OTP messages to account holders who have opted in.

Summary of the agent messaging program and its intended use

current_traffic

object

organic_website_traffic

object

Current organic website traffic range

min

integer(int64)

max

integer(int64)

existing_shortcode_traffic

boolean

exampletrue

Whether the brand currently uses a shortcode for messaging

shortcode_monthly_traffic

object

Monthly traffic volume range for the existing shortcode

min

integer(int64)

max

integer(int64)

shortcode

string

Max50

example12345

Existing shortcode number

carriers

array

Required

List of carrier identifiers to launch the agent on. Available carrier IDs can be retrieved from the /v2/channel-manager/rcs/metadata/carriers endpoint.

Example Request

Responses
Content Type
application/json

Created

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string(uuid)

Required

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Unique agent identifier

state

string

exampleDRAFT

Current state of the agent

Must be one of:DRAFTCREATEDPENDINGLAUNCHEDREJECTEDUNLAUNCHED

basic_info

object

Required

display_name

string

Required

Max40

exampleAcme Bank

Display name of the RCS agent shown to end users

sender_id

string

Required

Max50

exampleacme-bank

Unique sender identifier for the agent

hosting_region

string

Required

exampleEUROPE

Region where the agent is hosted

Must be one of:NORTH_AMERICAEUROPEASIA_PACIFIC

agent_purpose

string

Required

exampleTRANSACTIONAL

Intended use case of the agent

Must be one of:TRANSACTIONALPROMOTIONALOTPMULTI_USE

billing_category

string

Required

exampleCONVERSATIONAL

Billing category determining how messages are charged

Must be one of:BASIC_MESSAGESINGLE_MESSAGECONVERSATIONALNON_CONVERSATIONAL

brand_id

string(uuid)

Required

Max100

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Identifier of the brand this agent belongs to

account_manager_email

string

examplemanager@vonage.com

Vonage account manager email address

reseller_email

string

examplereseller@partner.com

Reseller email address, in case the agent is created by a reseller party

visual_design

object

tagline

string

Required

Max100

exampleYour trusted banking assistant

Short tagline describing the agent or brand

brand_color

string

Required

example#FF5733

Brand color in hex format, used for button text and UI elements above the agent phone number. Must meet a minimum contrast ratio of 4.5:1 against white (WCAG 2.0). See the support article

logo_image

string

examplehttps://cdn.example.com/logo.png

URL of the agent logo image. Shown as a circular avatar next to messages. Requirements: JPEG or PNG, 224x224 px, max 50 KB. See the support article

banner_image

string

examplehttps://cdn.example.com/banner.png

URL of the agent banner image. Displayed as a header when users view the agent business info. Requirements: JPEG, 1440x448 px, max 200 KB. See the support article

phone

array

Required

List of phone contact numbers (1-3)

number

string

Required

example+12025551234

Phone number in E.164 format

label

string

Max25

exampleCustomer Support

Display label for this phone number

array

Required

List of email contact addresses (1-3)

address

string

Required

Min1

examplesupport@example.com

Email address

label

string

Max25

exampleCustomer Support

Display label for this email address

website

array

Required

List of website links (1-3)

url

string

Required

examplehttps://www.example.com

Website URL

label

string

Max25

exampleOfficial Website

Display label for this website

privacy_policy

string

examplehttps://www.example.com/privacy

URL of the privacy policy

terms_of_service

string

examplehttps://www.example.com/terms

URL of the terms of service

application_settings

object

application_id

string

Required

examplea1b2c3d4-e5f6-7890-abcd-ef1234567890

Vonage application ID to associate with this agent

test_devices

array

string(uuid)

Required

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Unique test device identifier

phone

string

Required

example+12025551234

Phone number of the test device in E.164 format

created_at

string

Required

Date and time when the test device was added

status

string

Required

exampleACTIVE

Status of the test device registration

representative

object

first_name

string

Required

Max200

exampleJane

First name of the authorized representative

last_name

string

Required

Max200

exampleDoe

Last name of the authorized representative

title

string

Max200

exampleHead of Messaging

Job title of the authorized representative

string

Required

examplejane.doe@example.com

Email address of the authorized representative

brand_website

string

examplehttps://www.example.com

Brand website URL

phone

string

example+12025551234

Phone number in E.164 format

carrier_requirements

object

version

string

Required

examplev2

Carrier requirements schema version

points_of_contact

array

first_name

string

Required

Max200

exampleJohn

The first name of the point of contact for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the point of contact for the RCS Agent.

job_title

string

Required

Max200

exampleHead of Messaging

The job title of the point of contact for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the point of contact for the RCS Agent.

phone

string

example+12025551234

The phone number of the point of contact for the RCS Agent.

agent_preview

object

Required

agent_access_instructions

string

Required

Max10000

exampleVisit https://example.com/rcs-agent and follow the onboarding flow.

Instructions for reviewers on how to access and test the agent

urls

array

List of media URLs showcasing the agent (up to 10)

media_type

string

Required

exampleimage

Media type of the preview asset

Must be one of:imagevideo

url

string

Required

examplehttps://cdn.example.com/preview.png

URL of the preview asset

rcs_agent_discovery_methods

object

selection

array

Required

Methods through which users discover the RCS agent

other_input

string

Max500

examplePromoted via in-store QR codes

Additional details when OTHER is selected

consent_management

object

Required

user_messaging_consent_methods

object

Required

selection

array

Required

Selected consent methods

other_input

string

Max500

exampleUsers consent via in-store sign-up forms

Additional details when OTHER is selected

users_opt_in_process

object

Required

selection

array

Required

Selected opt-in methods

links

array

URLs where users can opt in (up to 10)

first_opt_in_message

string

Required

Max1000

exampleWelcome! You have successfully opted in to receive updates from Acme Bank.

The first message sent to users after opting in

users_opt_out_methods

object

Required

selection

array

Required

Selected opt-out methods

other_input

string

Max500

exampleUsers can opt out via the account settings page

Additional details when OTHER is selected

opt_out_processing_time

object

Required

selection

string

Required

exampleWITHIN_5_MINUTES

How quickly opt-out requests are processed

Must be one of:WITHIN_5_MINUTESWITHIN_24_HOURSOTHER

other_input

string

Max500

exampleProcessed within 2 business days

Additional details when OTHER is selected

opt_out_confirmation_message

object

Required

selection

string

Required

exampleSUCCESSFULLY_UNSUBSCRIBED

Confirmation message template sent after opt-out

Must be one of:SUCCESSFULLY_UNSUBSCRIBEDWONT_RECEIVE_FURTHER_MESSAGESOPT_OUT_REQUEST_PROCESSEDREPLY_START_TO_RESUBSCRIBEOPT_OUT_CONFIRMEDOTHER

other_input

string

Max500

exampleYou have been unsubscribed. Contact support@example.com to resubscribe.

Additional details when OTHER is selected

cta_language

string

Min1

Max2000

exampleReply YES to receive exclusive offers from Acme Bank.

Call-to-action language used in consent flows

engagement_flows

object

Required

agent_description

string

Required

Max5000

exampleAcme Bank RCS agent helps customers check balances, receive transaction alerts, and manage payments.

Description of what the agent does and how it engages with users

reasons_messages_sent

object

Required

Reasons why messages are sent to users

selection

array

Required

Selected reasons for sending messages

other_input

string

Max500

exampleSending loyalty program milestone notifications

Additional details when OTHER is selected

monthly_user_message_count

string

Required

exampleTHREE_FIVE_MESSAGES

Estimated number of messages sent to each user per month

Must be one of:ONE_TWO_MESSAGESTHREE_FIVE_MESSAGESSIX_TEN_MESSAGESELEVEN_TWENTY_MESSAGESMORE_THAN_TWENTY_ONE_MESSAGES

rcs_user_interaction_types

object

Required

Types of interactions users have with the agent

selection

array

Required

Selected types of RCS user interactions

other_input

string

Max500

exampleUsers interact via custom carousels

Additional details when OTHER is selected

help_interaction

string

Min1

Max2000

exampleReply HELP for assistance or visit https://www.example.com/support

How the agent responds to HELP messages from users

message_samples

array

Sample messages the agent will send to users (3-10 samples required)

message_type

string

exampleRICH_MEDIA

Type of RCS messages the agent sends. Use RICH_TEXT or RICH_MEDIA for US carriers; BASIC or SINGLE for non-US carriers.

Must be one of:RICH_TEXTRICH_MEDIABASICSINGLE

agent_summary

object

program_summary

string

Min1

Max2000

exampleAcme Bank sends transactional alerts and OTP messages to account holders who have opted in.

Summary of the agent messaging program and its intended use

current_traffic

object

organic_website_traffic

object

Current organic website traffic range

min

integer(int64)

max

integer(int64)

existing_shortcode_traffic

boolean

exampletrue

Whether the brand currently uses a shortcode for messaging

shortcode_monthly_traffic

object

Monthly traffic volume range for the existing shortcode

min

integer(int64)

max

integer(int64)

shortcode

string

Max50

example12345

Existing shortcode number

carriers

array

string

Required

examplegoogle-us-att

Carrier identifier

launch_state

string

Current launch state for this carrier

update_time

string

Date and time of the last status update

launch_submitted_at

string

Date and time when the launch was submitted for this carrier

comment

string

Comment or reason associated with the current launch state

verification_details

object

status

string

exampleVERIFICATION_STATE_VERIFIED

Verification status of the agent

Must be one of:VERIFICATION_STATE_UNSPECIFIEDVERIFICATION_STATE_UNVERIFIEDVERIFICATION_STATE_PENDINGVERIFICATION_STATE_VERIFIED

brand_details

object

organization_name

string

Required

Max255

legal_form

string

Required

Max50

stock_symbol

string

Max12

legal_entity_type

string

Required

Max50

country_of_registration

string

Required

Min2

Max2

federal_tax_id

string

Max50

business_website_url

string

Required

Max255

address_line1

string

Required

Max255

address_line2

string

Max255

city

string

Required

Max100

state_or_province

string

Required

Max100

zip_or_post_code

string

Required

Max15

launch_submitted_at

string

Date and time when the agent launch was submitted

created_at

string

Date and time when the agent was created

updated_at

string

Date and time when the agent was last updated

Example Response

Get Agent

Retrieve an existing RCS Agent.

gethttps://api.nexmo.com/v2/channel-manager/rcs/agents/:agent_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

agent_id

string

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

Agent ID

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string(uuid)

Required

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Unique agent identifier

state

string

exampleDRAFT

Current state of the agent

Must be one of:DRAFTCREATEDPENDINGLAUNCHEDREJECTEDUNLAUNCHED

basic_info

object

Required

display_name

string

Required

Max40

exampleAcme Bank

Display name of the RCS agent shown to end users

sender_id

string

Required

Max50

exampleacme-bank

Unique sender identifier for the agent

hosting_region

string

Required

exampleEUROPE

Region where the agent is hosted

Must be one of:NORTH_AMERICAEUROPEASIA_PACIFIC

agent_purpose

string

Required

exampleTRANSACTIONAL

Intended use case of the agent

Must be one of:TRANSACTIONALPROMOTIONALOTPMULTI_USE

billing_category

string

Required

exampleCONVERSATIONAL

Billing category determining how messages are charged

Must be one of:BASIC_MESSAGESINGLE_MESSAGECONVERSATIONALNON_CONVERSATIONAL

brand_id

string(uuid)

Required

Max100

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Identifier of the brand this agent belongs to

account_manager_email

string

examplemanager@vonage.com

Vonage account manager email address

reseller_email

string

examplereseller@partner.com

Reseller email address, in case the agent is created by a reseller party

visual_design

object

tagline

string

Required

Max100

exampleYour trusted banking assistant

Short tagline describing the agent or brand

brand_color

string

Required

example#FF5733

Brand color in hex format, used for button text and UI elements above the agent phone number. Must meet a minimum contrast ratio of 4.5:1 against white (WCAG 2.0). See the support article

logo_image

string

examplehttps://cdn.example.com/logo.png

URL of the agent logo image. Shown as a circular avatar next to messages. Requirements: JPEG or PNG, 224x224 px, max 50 KB. See the support article

banner_image

string

examplehttps://cdn.example.com/banner.png

URL of the agent banner image. Displayed as a header when users view the agent business info. Requirements: JPEG, 1440x448 px, max 200 KB. See the support article

phone

array

Required

List of phone contact numbers (1-3)

number

string

Required

example+12025551234

Phone number in E.164 format

label

string

Max25

exampleCustomer Support

Display label for this phone number

array

Required

List of email contact addresses (1-3)

address

string

Required

Min1

examplesupport@example.com

Email address

label

string

Max25

exampleCustomer Support

Display label for this email address

website

array

Required

List of website links (1-3)

url

string

Required

examplehttps://www.example.com

Website URL

label

string

Max25

exampleOfficial Website

Display label for this website

privacy_policy

string

examplehttps://www.example.com/privacy

URL of the privacy policy

terms_of_service

string

examplehttps://www.example.com/terms

URL of the terms of service

application_settings

object

application_id

string

Required

examplea1b2c3d4-e5f6-7890-abcd-ef1234567890

Vonage application ID to associate with this agent

test_devices

array

string(uuid)

Required

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Unique test device identifier

phone

string

Required

example+12025551234

Phone number of the test device in E.164 format

created_at

string

Required

Date and time when the test device was added

status

string

Required

exampleACTIVE

Status of the test device registration

representative

object

first_name

string

Required

Max200

exampleJane

First name of the authorized representative

last_name

string

Required

Max200

exampleDoe

Last name of the authorized representative

title

string

Max200

exampleHead of Messaging

Job title of the authorized representative

string

Required

examplejane.doe@example.com

Email address of the authorized representative

brand_website

string

examplehttps://www.example.com

Brand website URL

phone

string

example+12025551234

Phone number in E.164 format

carrier_requirements

object

version

string

Required

examplev2

Carrier requirements schema version

points_of_contact

array

first_name

string

Required

Max200

exampleJohn

The first name of the point of contact for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the point of contact for the RCS Agent.

job_title

string

Required

Max200

exampleHead of Messaging

The job title of the point of contact for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the point of contact for the RCS Agent.

phone

string

example+12025551234

The phone number of the point of contact for the RCS Agent.

agent_preview

object

Required

agent_access_instructions

string

Required

Max10000

exampleVisit https://example.com/rcs-agent and follow the onboarding flow.

Instructions for reviewers on how to access and test the agent

urls

array

List of media URLs showcasing the agent (up to 10)

media_type

string

Required

exampleimage

Media type of the preview asset

Must be one of:imagevideo

url

string

Required

examplehttps://cdn.example.com/preview.png

URL of the preview asset

rcs_agent_discovery_methods

object

selection

array

Required

Methods through which users discover the RCS agent

other_input

string

Max500

examplePromoted via in-store QR codes

Additional details when OTHER is selected

consent_management

object

Required

user_messaging_consent_methods

object

Required

selection

array

Required

Selected consent methods

other_input

string

Max500

exampleUsers consent via in-store sign-up forms

Additional details when OTHER is selected

users_opt_in_process

object

Required

selection

array

Required

Selected opt-in methods

links

array

URLs where users can opt in (up to 10)

first_opt_in_message

string

Required

Max1000

exampleWelcome! You have successfully opted in to receive updates from Acme Bank.

The first message sent to users after opting in

users_opt_out_methods

object

Required

selection

array

Required

Selected opt-out methods

other_input

string

Max500

exampleUsers can opt out via the account settings page

Additional details when OTHER is selected

opt_out_processing_time

object

Required

selection

string

Required

exampleWITHIN_5_MINUTES

How quickly opt-out requests are processed

Must be one of:WITHIN_5_MINUTESWITHIN_24_HOURSOTHER

other_input

string

Max500

exampleProcessed within 2 business days

Additional details when OTHER is selected

opt_out_confirmation_message

object

Required

selection

string

Required

exampleSUCCESSFULLY_UNSUBSCRIBED

Confirmation message template sent after opt-out

Must be one of:SUCCESSFULLY_UNSUBSCRIBEDWONT_RECEIVE_FURTHER_MESSAGESOPT_OUT_REQUEST_PROCESSEDREPLY_START_TO_RESUBSCRIBEOPT_OUT_CONFIRMEDOTHER

other_input

string

Max500

exampleYou have been unsubscribed. Contact support@example.com to resubscribe.

Additional details when OTHER is selected

cta_language

string

Min1

Max2000

exampleReply YES to receive exclusive offers from Acme Bank.

Call-to-action language used in consent flows

engagement_flows

object

Required

agent_description

string

Required

Max5000

exampleAcme Bank RCS agent helps customers check balances, receive transaction alerts, and manage payments.

Description of what the agent does and how it engages with users

reasons_messages_sent

object

Required

Reasons why messages are sent to users

selection

array

Required

Selected reasons for sending messages

other_input

string

Max500

exampleSending loyalty program milestone notifications

Additional details when OTHER is selected

monthly_user_message_count

string

Required

exampleTHREE_FIVE_MESSAGES

Estimated number of messages sent to each user per month

Must be one of:ONE_TWO_MESSAGESTHREE_FIVE_MESSAGESSIX_TEN_MESSAGESELEVEN_TWENTY_MESSAGESMORE_THAN_TWENTY_ONE_MESSAGES

rcs_user_interaction_types

object

Required

Types of interactions users have with the agent

selection

array

Required

Selected types of RCS user interactions

other_input

string

Max500

exampleUsers interact via custom carousels

Additional details when OTHER is selected

help_interaction

string

Min1

Max2000

exampleReply HELP for assistance or visit https://www.example.com/support

How the agent responds to HELP messages from users

message_samples

array

Sample messages the agent will send to users (3-10 samples required)

message_type

string

exampleRICH_MEDIA

Type of RCS messages the agent sends. Use RICH_TEXT or RICH_MEDIA for US carriers; BASIC or SINGLE for non-US carriers.

Must be one of:RICH_TEXTRICH_MEDIABASICSINGLE

agent_summary

object

program_summary

string

Min1

Max2000

exampleAcme Bank sends transactional alerts and OTP messages to account holders who have opted in.

Summary of the agent messaging program and its intended use

current_traffic

object

organic_website_traffic

object

Current organic website traffic range

min

integer(int64)

max

integer(int64)

existing_shortcode_traffic

boolean

exampletrue

Whether the brand currently uses a shortcode for messaging

shortcode_monthly_traffic

object

Monthly traffic volume range for the existing shortcode

min

integer(int64)

max

integer(int64)

shortcode

string

Max50

example12345

Existing shortcode number

carriers

array

string

Required

examplegoogle-us-att

Carrier identifier

launch_state

string

Current launch state for this carrier

update_time

string

Date and time of the last status update

launch_submitted_at

string

Date and time when the launch was submitted for this carrier

comment

string

Comment or reason associated with the current launch state

verification_details

object

status

string

exampleVERIFICATION_STATE_VERIFIED

Verification status of the agent

Must be one of:VERIFICATION_STATE_UNSPECIFIEDVERIFICATION_STATE_UNVERIFIEDVERIFICATION_STATE_PENDINGVERIFICATION_STATE_VERIFIED

brand_details

object

organization_name

string

Required

Max255

legal_form

string

Required

Max50

stock_symbol

string

Max12

legal_entity_type

string

Required

Max50

country_of_registration

string

Required

Min2

Max2

federal_tax_id

string

Max50

business_website_url

string

Required

Max255

address_line1

string

Required

Max255

address_line2

string

Max255

city

string

Required

Max100

state_or_province

string

Required

Max100

zip_or_post_code

string

Required

Max15

launch_submitted_at

string

Date and time when the agent launch was submitted

created_at

string

Date and time when the agent was created

updated_at

string

Date and time when the agent was last updated

Example Response

Update Agent

Fully update an existing RCS Agent.

puthttps://api.nexmo.com/v2/channel-manager/rcs/agents/:agent_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

agent_id

string

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

Agent ID

Request Body
Content Type
application/json

basic_info

object

Required

display_name

string

Required

Max40

exampleAcme Bank

Display name of the RCS agent shown to end users

sender_id

string

Required

Max50

exampleacme-bank

Unique sender identifier for the agent

hosting_region

string

Required

exampleEUROPE

Region where the agent is hosted

Must be one of:NORTH_AMERICAEUROPEASIA_PACIFIC

agent_purpose

string

Required

exampleTRANSACTIONAL

Intended use case of the agent

Must be one of:TRANSACTIONALPROMOTIONALOTPMULTI_USE

billing_category

string

Required

exampleCONVERSATIONAL

Billing category determining how messages are charged

Must be one of:BASIC_MESSAGESINGLE_MESSAGECONVERSATIONALNON_CONVERSATIONAL

brand_id

string(uuid)

Required

Max100

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Identifier of the brand this agent belongs to

account_manager_email

string

examplemanager@vonage.com

Vonage account manager email address

reseller_email

string

examplereseller@partner.com

Reseller email address, in case the agent is created by a reseller party

visual_design

object

Required

tagline

string

Required

Max100

exampleYour trusted banking assistant

Short tagline describing the agent or brand

brand_color

string

Required

example#FF5733

Brand color in hex format, used for button text and UI elements above the agent phone number. Must meet a minimum contrast ratio of 4.5:1 against white (WCAG 2.0). See the support article

logo_image

string

examplehttps://cdn.example.com/logo.png

URL of the agent logo image. Shown as a circular avatar next to messages. Requirements: JPEG or PNG, 224x224 px, max 50 KB. See the support article

banner_image

string

examplehttps://cdn.example.com/banner.png

URL of the agent banner image. Displayed as a header when users view the agent business info. Requirements: JPEG, 1440x448 px, max 200 KB. See the support article

phone

array

Required

List of phone contact numbers (1-3)

number

string

Required

example+12025551234

Phone number in E.164 format

label

string

Max25

exampleCustomer Support

Display label for this phone number

array

Required

List of email contact addresses (1-3)

address

string

Required

Min1

examplesupport@example.com

Email address

label

string

Max25

exampleCustomer Support

Display label for this email address

website

array

Required

List of website links (1-3)

url

string

Required

examplehttps://www.example.com

Website URL

label

string

Max25

exampleOfficial Website

Display label for this website

privacy_policy

string

examplehttps://www.example.com/privacy

URL of the privacy policy

terms_of_service

string

examplehttps://www.example.com/terms

URL of the terms of service

application_settings

object

Required

application_id

string

Required

examplea1b2c3d4-e5f6-7890-abcd-ef1234567890

Vonage application ID to associate with this agent

representative

object

Required

first_name

string

Required

Max200

exampleJane

First name of the authorized representative

last_name

string

Required

Max200

exampleDoe

Last name of the authorized representative

title

string

Max200

exampleHead of Messaging

Job title of the authorized representative

string

Required

examplejane.doe@example.com

Email address of the authorized representative

brand_website

string

examplehttps://www.example.com

Brand website URL

phone

string

example+12025551234

Phone number in E.164 format

carrier_requirements

object

Required

version

string

Required

examplev2

Carrier requirements schema version

points_of_contact

array

first_name

string

Required

Max200

exampleJohn

The first name of the point of contact for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the point of contact for the RCS Agent.

job_title

string

Required

Max200

exampleHead of Messaging

The job title of the point of contact for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the point of contact for the RCS Agent.

phone

string

example+12025551234

The phone number of the point of contact for the RCS Agent.

agent_preview

object

Required

agent_access_instructions

string

Required

Max10000

exampleVisit https://example.com/rcs-agent and follow the onboarding flow.

Instructions for reviewers on how to access and test the agent

urls

array

List of media URLs showcasing the agent (up to 10)

media_type

string

Required

exampleimage

Media type of the preview asset

Must be one of:imagevideo

url

string

Required

examplehttps://cdn.example.com/preview.png

URL of the preview asset

rcs_agent_discovery_methods

object

selection

array

Required

Methods through which users discover the RCS agent

other_input

string

Max500

examplePromoted via in-store QR codes

Additional details when OTHER is selected

consent_management

object

Required

user_messaging_consent_methods

object

Required

selection

array

Required

Selected consent methods

other_input

string

Max500

exampleUsers consent via in-store sign-up forms

Additional details when OTHER is selected

users_opt_in_process

object

Required

selection

array

Required

Selected opt-in methods

links

array

URLs where users can opt in (up to 10)

first_opt_in_message

string

Required

Max1000

exampleWelcome! You have successfully opted in to receive updates from Acme Bank.

The first message sent to users after opting in

users_opt_out_methods

object

Required

selection

array

Required

Selected opt-out methods

other_input

string

Max500

exampleUsers can opt out via the account settings page

Additional details when OTHER is selected

opt_out_processing_time

object

Required

selection

string

Required

exampleWITHIN_5_MINUTES

How quickly opt-out requests are processed

Must be one of:WITHIN_5_MINUTESWITHIN_24_HOURSOTHER

other_input

string

Max500

exampleProcessed within 2 business days

Additional details when OTHER is selected

opt_out_confirmation_message

object

Required

selection

string

Required

exampleSUCCESSFULLY_UNSUBSCRIBED

Confirmation message template sent after opt-out

Must be one of:SUCCESSFULLY_UNSUBSCRIBEDWONT_RECEIVE_FURTHER_MESSAGESOPT_OUT_REQUEST_PROCESSEDREPLY_START_TO_RESUBSCRIBEOPT_OUT_CONFIRMEDOTHER

other_input

string

Max500

exampleYou have been unsubscribed. Contact support@example.com to resubscribe.

Additional details when OTHER is selected

cta_language

string

Min1

Max2000

exampleReply YES to receive exclusive offers from Acme Bank.

Call-to-action language used in consent flows

engagement_flows

object

Required

agent_description

string

Required

Max5000

exampleAcme Bank RCS agent helps customers check balances, receive transaction alerts, and manage payments.

Description of what the agent does and how it engages with users

reasons_messages_sent

object

Required

Reasons why messages are sent to users

selection

array

Required

Selected reasons for sending messages

other_input

string

Max500

exampleSending loyalty program milestone notifications

Additional details when OTHER is selected

monthly_user_message_count

string

Required

exampleTHREE_FIVE_MESSAGES

Estimated number of messages sent to each user per month

Must be one of:ONE_TWO_MESSAGESTHREE_FIVE_MESSAGESSIX_TEN_MESSAGESELEVEN_TWENTY_MESSAGESMORE_THAN_TWENTY_ONE_MESSAGES

rcs_user_interaction_types

object

Required

Types of interactions users have with the agent

selection

array

Required

Selected types of RCS user interactions

other_input

string

Max500

exampleUsers interact via custom carousels

Additional details when OTHER is selected

help_interaction

string

Min1

Max2000

exampleReply HELP for assistance or visit https://www.example.com/support

How the agent responds to HELP messages from users

message_samples

array

Sample messages the agent will send to users (3-10 samples required)

message_type

string

exampleRICH_MEDIA

Type of RCS messages the agent sends. Use RICH_TEXT or RICH_MEDIA for US carriers; BASIC or SINGLE for non-US carriers.

Must be one of:RICH_TEXTRICH_MEDIABASICSINGLE

agent_summary

object

program_summary

string

Min1

Max2000

exampleAcme Bank sends transactional alerts and OTP messages to account holders who have opted in.

Summary of the agent messaging program and its intended use

current_traffic

object

organic_website_traffic

object

Current organic website traffic range

min

integer(int64)

max

integer(int64)

existing_shortcode_traffic

boolean

exampletrue

Whether the brand currently uses a shortcode for messaging

shortcode_monthly_traffic

object

Monthly traffic volume range for the existing shortcode

min

integer(int64)

max

integer(int64)

shortcode

string

Max50

example12345

Existing shortcode number

carriers

array

Required

Example Request

Responses
Content Type
application/json

Accepted

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string(uuid)

Required

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Unique agent identifier

state

string

exampleDRAFT

Current state of the agent

Must be one of:DRAFTCREATEDPENDINGLAUNCHEDREJECTEDUNLAUNCHED

basic_info

object

Required

display_name

string

Required

Max40

exampleAcme Bank

Display name of the RCS agent shown to end users

sender_id

string

Required

Max50

exampleacme-bank

Unique sender identifier for the agent

hosting_region

string

Required

exampleEUROPE

Region where the agent is hosted

Must be one of:NORTH_AMERICAEUROPEASIA_PACIFIC

agent_purpose

string

Required

exampleTRANSACTIONAL

Intended use case of the agent

Must be one of:TRANSACTIONALPROMOTIONALOTPMULTI_USE

billing_category

string

Required

exampleCONVERSATIONAL

Billing category determining how messages are charged

Must be one of:BASIC_MESSAGESINGLE_MESSAGECONVERSATIONALNON_CONVERSATIONAL

brand_id

string(uuid)

Required

Max100

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Identifier of the brand this agent belongs to

account_manager_email

string

examplemanager@vonage.com

Vonage account manager email address

reseller_email

string

examplereseller@partner.com

Reseller email address, in case the agent is created by a reseller party

visual_design

object

tagline

string

Required

Max100

exampleYour trusted banking assistant

Short tagline describing the agent or brand

brand_color

string

Required

example#FF5733

Brand color in hex format, used for button text and UI elements above the agent phone number. Must meet a minimum contrast ratio of 4.5:1 against white (WCAG 2.0). See the support article

logo_image

string

examplehttps://cdn.example.com/logo.png

URL of the agent logo image. Shown as a circular avatar next to messages. Requirements: JPEG or PNG, 224x224 px, max 50 KB. See the support article

banner_image

string

examplehttps://cdn.example.com/banner.png

URL of the agent banner image. Displayed as a header when users view the agent business info. Requirements: JPEG, 1440x448 px, max 200 KB. See the support article

phone

array

Required

List of phone contact numbers (1-3)

number

string

Required

example+12025551234

Phone number in E.164 format

label

string

Max25

exampleCustomer Support

Display label for this phone number

array

Required

List of email contact addresses (1-3)

address

string

Required

Min1

examplesupport@example.com

Email address

label

string

Max25

exampleCustomer Support

Display label for this email address

website

array

Required

List of website links (1-3)

url

string

Required

examplehttps://www.example.com

Website URL

label

string

Max25

exampleOfficial Website

Display label for this website

privacy_policy

string

examplehttps://www.example.com/privacy

URL of the privacy policy

terms_of_service

string

examplehttps://www.example.com/terms

URL of the terms of service

application_settings

object

application_id

string

Required

examplea1b2c3d4-e5f6-7890-abcd-ef1234567890

Vonage application ID to associate with this agent

test_devices

array

string(uuid)

Required

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Unique test device identifier

phone

string

Required

example+12025551234

Phone number of the test device in E.164 format

created_at

string

Required

Date and time when the test device was added

status

string

Required

exampleACTIVE

Status of the test device registration

representative

object

first_name

string

Required

Max200

exampleJane

First name of the authorized representative

last_name

string

Required

Max200

exampleDoe

Last name of the authorized representative

title

string

Max200

exampleHead of Messaging

Job title of the authorized representative

string

Required

examplejane.doe@example.com

Email address of the authorized representative

brand_website

string

examplehttps://www.example.com

Brand website URL

phone

string

example+12025551234

Phone number in E.164 format

carrier_requirements

object

version

string

Required

examplev2

Carrier requirements schema version

points_of_contact

array

first_name

string

Required

Max200

exampleJohn

The first name of the point of contact for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the point of contact for the RCS Agent.

job_title

string

Required

Max200

exampleHead of Messaging

The job title of the point of contact for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the point of contact for the RCS Agent.

phone

string

example+12025551234

The phone number of the point of contact for the RCS Agent.

agent_preview

object

Required

agent_access_instructions

string

Required

Max10000

exampleVisit https://example.com/rcs-agent and follow the onboarding flow.

Instructions for reviewers on how to access and test the agent

urls

array

List of media URLs showcasing the agent (up to 10)

media_type

string

Required

exampleimage

Media type of the preview asset

Must be one of:imagevideo

url

string

Required

examplehttps://cdn.example.com/preview.png

URL of the preview asset

rcs_agent_discovery_methods

object

selection

array

Required

Methods through which users discover the RCS agent

other_input

string

Max500

examplePromoted via in-store QR codes

Additional details when OTHER is selected

consent_management

object

Required

user_messaging_consent_methods

object

Required

selection

array

Required

Selected consent methods

other_input

string

Max500

exampleUsers consent via in-store sign-up forms

Additional details when OTHER is selected

users_opt_in_process

object

Required

selection

array

Required

Selected opt-in methods

links

array

URLs where users can opt in (up to 10)

first_opt_in_message

string

Required

Max1000

exampleWelcome! You have successfully opted in to receive updates from Acme Bank.

The first message sent to users after opting in

users_opt_out_methods

object

Required

selection

array

Required

Selected opt-out methods

other_input

string

Max500

exampleUsers can opt out via the account settings page

Additional details when OTHER is selected

opt_out_processing_time

object

Required

selection

string

Required

exampleWITHIN_5_MINUTES

How quickly opt-out requests are processed

Must be one of:WITHIN_5_MINUTESWITHIN_24_HOURSOTHER

other_input

string

Max500

exampleProcessed within 2 business days

Additional details when OTHER is selected

opt_out_confirmation_message

object

Required

selection

string

Required

exampleSUCCESSFULLY_UNSUBSCRIBED

Confirmation message template sent after opt-out

Must be one of:SUCCESSFULLY_UNSUBSCRIBEDWONT_RECEIVE_FURTHER_MESSAGESOPT_OUT_REQUEST_PROCESSEDREPLY_START_TO_RESUBSCRIBEOPT_OUT_CONFIRMEDOTHER

other_input

string

Max500

exampleYou have been unsubscribed. Contact support@example.com to resubscribe.

Additional details when OTHER is selected

cta_language

string

Min1

Max2000

exampleReply YES to receive exclusive offers from Acme Bank.

Call-to-action language used in consent flows

engagement_flows

object

Required

agent_description

string

Required

Max5000

exampleAcme Bank RCS agent helps customers check balances, receive transaction alerts, and manage payments.

Description of what the agent does and how it engages with users

reasons_messages_sent

object

Required

Reasons why messages are sent to users

selection

array

Required

Selected reasons for sending messages

other_input

string

Max500

exampleSending loyalty program milestone notifications

Additional details when OTHER is selected

monthly_user_message_count

string

Required

exampleTHREE_FIVE_MESSAGES

Estimated number of messages sent to each user per month

Must be one of:ONE_TWO_MESSAGESTHREE_FIVE_MESSAGESSIX_TEN_MESSAGESELEVEN_TWENTY_MESSAGESMORE_THAN_TWENTY_ONE_MESSAGES

rcs_user_interaction_types

object

Required

Types of interactions users have with the agent

selection

array

Required

Selected types of RCS user interactions

other_input

string

Max500

exampleUsers interact via custom carousels

Additional details when OTHER is selected

help_interaction

string

Min1

Max2000

exampleReply HELP for assistance or visit https://www.example.com/support

How the agent responds to HELP messages from users

message_samples

array

Sample messages the agent will send to users (3-10 samples required)

message_type

string

exampleRICH_MEDIA

Type of RCS messages the agent sends. Use RICH_TEXT or RICH_MEDIA for US carriers; BASIC or SINGLE for non-US carriers.

Must be one of:RICH_TEXTRICH_MEDIABASICSINGLE

agent_summary

object

program_summary

string

Min1

Max2000

exampleAcme Bank sends transactional alerts and OTP messages to account holders who have opted in.

Summary of the agent messaging program and its intended use

current_traffic

object

organic_website_traffic

object

Current organic website traffic range

min

integer(int64)

max

integer(int64)

existing_shortcode_traffic

boolean

exampletrue

Whether the brand currently uses a shortcode for messaging

shortcode_monthly_traffic

object

Monthly traffic volume range for the existing shortcode

min

integer(int64)

max

integer(int64)

shortcode

string

Max50

example12345

Existing shortcode number

carriers

array

string

Required

examplegoogle-us-att

Carrier identifier

launch_state

string

Current launch state for this carrier

update_time

string

Date and time of the last status update

launch_submitted_at

string

Date and time when the launch was submitted for this carrier

comment

string

Comment or reason associated with the current launch state

verification_details

object

status

string

exampleVERIFICATION_STATE_VERIFIED

Verification status of the agent

Must be one of:VERIFICATION_STATE_UNSPECIFIEDVERIFICATION_STATE_UNVERIFIEDVERIFICATION_STATE_PENDINGVERIFICATION_STATE_VERIFIED

brand_details

object

organization_name

string

Required

Max255

legal_form

string

Required

Max50

stock_symbol

string

Max12

legal_entity_type

string

Required

Max50

country_of_registration

string

Required

Min2

Max2

federal_tax_id

string

Max50

business_website_url

string

Required

Max255

address_line1

string

Required

Max255

address_line2

string

Max255

city

string

Required

Max100

state_or_province

string

Required

Max100

zip_or_post_code

string

Required

Max15

launch_submitted_at

string

Date and time when the agent launch was submitted

created_at

string

Date and time when the agent was created

updated_at

string

Date and time when the agent was last updated

Example Response

Partially Update Agent

Partially update an existing RCS Agent.

patchhttps://api.nexmo.com/v2/channel-manager/rcs/agents/:agent_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

agent_id

string

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

Agent ID

Request Body
Content Type
application/json

basic_info

object

display_name

string

Required

Max40

exampleAcme Bank

Display name of the RCS agent shown to end users

sender_id

string

Required

Max50

exampleacme-bank

Unique sender identifier for the agent

hosting_region

string

Required

exampleEUROPE

Region where the agent is hosted

Must be one of:NORTH_AMERICAEUROPEASIA_PACIFIC

agent_purpose

string

Required

exampleTRANSACTIONAL

Intended use case of the agent

Must be one of:TRANSACTIONALPROMOTIONALOTPMULTI_USE

billing_category

string

Required

exampleCONVERSATIONAL

Billing category determining how messages are charged

Must be one of:BASIC_MESSAGESINGLE_MESSAGECONVERSATIONALNON_CONVERSATIONAL

brand_id

string(uuid)

Required

Max100

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Identifier of the brand this agent belongs to

account_manager_email

string

examplemanager@vonage.com

Vonage account manager email address

reseller_email

string

examplereseller@partner.com

Reseller email address, in case the agent is created by a reseller party

visual_design

object

tagline

string

Required

Max100

exampleYour trusted banking assistant

Short tagline describing the agent or brand

brand_color

string

Required

example#FF5733

Brand color in hex format, used for button text and UI elements above the agent phone number. Must meet a minimum contrast ratio of 4.5:1 against white (WCAG 2.0). See the support article

logo_image

string

examplehttps://cdn.example.com/logo.png

URL of the agent logo image. Shown as a circular avatar next to messages. Requirements: JPEG or PNG, 224x224 px, max 50 KB. See the support article

banner_image

string

examplehttps://cdn.example.com/banner.png

URL of the agent banner image. Displayed as a header when users view the agent business info. Requirements: JPEG, 1440x448 px, max 200 KB. See the support article

phone

array

Required

List of phone contact numbers (1-3)

number

string

Required

example+12025551234

Phone number in E.164 format

label

string

Max25

exampleCustomer Support

Display label for this phone number

array

Required

List of email contact addresses (1-3)

address

string

Required

Min1

examplesupport@example.com

Email address

label

string

Max25

exampleCustomer Support

Display label for this email address

website

array

Required

List of website links (1-3)

url

string

Required

examplehttps://www.example.com

Website URL

label

string

Max25

exampleOfficial Website

Display label for this website

privacy_policy

string

examplehttps://www.example.com/privacy

URL of the privacy policy

terms_of_service

string

examplehttps://www.example.com/terms

URL of the terms of service

application_settings

object

application_id

string

Required

examplea1b2c3d4-e5f6-7890-abcd-ef1234567890

Vonage application ID to associate with this agent

representative

object

first_name

string

Required

Max200

exampleJane

First name of the authorized representative

last_name

string

Required

Max200

exampleDoe

Last name of the authorized representative

title

string

Max200

exampleHead of Messaging

Job title of the authorized representative

string

Required

examplejane.doe@example.com

Email address of the authorized representative

brand_website

string

examplehttps://www.example.com

Brand website URL

phone

string

example+12025551234

Phone number in E.164 format

carrier_requirements

object

version

string

Required

examplev2

Carrier requirements schema version

points_of_contact

array

first_name

string

Required

Max200

exampleJohn

The first name of the point of contact for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the point of contact for the RCS Agent.

job_title

string

Required

Max200

exampleHead of Messaging

The job title of the point of contact for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the point of contact for the RCS Agent.

phone

string

example+12025551234

The phone number of the point of contact for the RCS Agent.

agent_preview

object

Required

agent_access_instructions

string

Required

Max10000

exampleVisit https://example.com/rcs-agent and follow the onboarding flow.

Instructions for reviewers on how to access and test the agent

urls

array

List of media URLs showcasing the agent (up to 10)

media_type

string

Required

exampleimage

Media type of the preview asset

Must be one of:imagevideo

url

string

Required

examplehttps://cdn.example.com/preview.png

URL of the preview asset

rcs_agent_discovery_methods

object

selection

array

Required

Methods through which users discover the RCS agent

other_input

string

Max500

examplePromoted via in-store QR codes

Additional details when OTHER is selected

consent_management

object

Required

user_messaging_consent_methods

object

Required

selection

array

Required

Selected consent methods

other_input

string

Max500

exampleUsers consent via in-store sign-up forms

Additional details when OTHER is selected

users_opt_in_process

object

Required

selection

array

Required

Selected opt-in methods

links

array

URLs where users can opt in (up to 10)

first_opt_in_message

string

Required

Max1000

exampleWelcome! You have successfully opted in to receive updates from Acme Bank.

The first message sent to users after opting in

users_opt_out_methods

object

Required

selection

array

Required

Selected opt-out methods

other_input

string

Max500

exampleUsers can opt out via the account settings page

Additional details when OTHER is selected

opt_out_processing_time

object

Required

selection

string

Required

exampleWITHIN_5_MINUTES

How quickly opt-out requests are processed

Must be one of:WITHIN_5_MINUTESWITHIN_24_HOURSOTHER

other_input

string

Max500

exampleProcessed within 2 business days

Additional details when OTHER is selected

opt_out_confirmation_message

object

Required

selection

string

Required

exampleSUCCESSFULLY_UNSUBSCRIBED

Confirmation message template sent after opt-out

Must be one of:SUCCESSFULLY_UNSUBSCRIBEDWONT_RECEIVE_FURTHER_MESSAGESOPT_OUT_REQUEST_PROCESSEDREPLY_START_TO_RESUBSCRIBEOPT_OUT_CONFIRMEDOTHER

other_input

string

Max500

exampleYou have been unsubscribed. Contact support@example.com to resubscribe.

Additional details when OTHER is selected

cta_language

string

Min1

Max2000

exampleReply YES to receive exclusive offers from Acme Bank.

Call-to-action language used in consent flows

engagement_flows

object

Required

agent_description

string

Required

Max5000

exampleAcme Bank RCS agent helps customers check balances, receive transaction alerts, and manage payments.

Description of what the agent does and how it engages with users

reasons_messages_sent

object

Required

Reasons why messages are sent to users

selection

array

Required

Selected reasons for sending messages

other_input

string

Max500

exampleSending loyalty program milestone notifications

Additional details when OTHER is selected

monthly_user_message_count

string

Required

exampleTHREE_FIVE_MESSAGES

Estimated number of messages sent to each user per month

Must be one of:ONE_TWO_MESSAGESTHREE_FIVE_MESSAGESSIX_TEN_MESSAGESELEVEN_TWENTY_MESSAGESMORE_THAN_TWENTY_ONE_MESSAGES

rcs_user_interaction_types

object

Required

Types of interactions users have with the agent

selection

array

Required

Selected types of RCS user interactions

other_input

string

Max500

exampleUsers interact via custom carousels

Additional details when OTHER is selected

help_interaction

string

Min1

Max2000

exampleReply HELP for assistance or visit https://www.example.com/support

How the agent responds to HELP messages from users

message_samples

array

Sample messages the agent will send to users (3-10 samples required)

message_type

string

exampleRICH_MEDIA

Type of RCS messages the agent sends. Use RICH_TEXT or RICH_MEDIA for US carriers; BASIC or SINGLE for non-US carriers.

Must be one of:RICH_TEXTRICH_MEDIABASICSINGLE

agent_summary

object

program_summary

string

Min1

Max2000

exampleAcme Bank sends transactional alerts and OTP messages to account holders who have opted in.

Summary of the agent messaging program and its intended use

current_traffic

object

organic_website_traffic

object

Current organic website traffic range

min

integer(int64)

max

integer(int64)

existing_shortcode_traffic

boolean

exampletrue

Whether the brand currently uses a shortcode for messaging

shortcode_monthly_traffic

object

Monthly traffic volume range for the existing shortcode

min

integer(int64)

max

integer(int64)

shortcode

string

Max50

example12345

Existing shortcode number

carriers

array

Example Request

Responses
Content Type
application/json

Accepted

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string(uuid)

Required

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Unique agent identifier

state

string

exampleDRAFT

Current state of the agent

Must be one of:DRAFTCREATEDPENDINGLAUNCHEDREJECTEDUNLAUNCHED

basic_info

object

Required

display_name

string

Required

Max40

exampleAcme Bank

Display name of the RCS agent shown to end users

sender_id

string

Required

Max50

exampleacme-bank

Unique sender identifier for the agent

hosting_region

string

Required

exampleEUROPE

Region where the agent is hosted

Must be one of:NORTH_AMERICAEUROPEASIA_PACIFIC

agent_purpose

string

Required

exampleTRANSACTIONAL

Intended use case of the agent

Must be one of:TRANSACTIONALPROMOTIONALOTPMULTI_USE

billing_category

string

Required

exampleCONVERSATIONAL

Billing category determining how messages are charged

Must be one of:BASIC_MESSAGESINGLE_MESSAGECONVERSATIONALNON_CONVERSATIONAL

brand_id

string(uuid)

Required

Max100

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Identifier of the brand this agent belongs to

account_manager_email

string

examplemanager@vonage.com

Vonage account manager email address

reseller_email

string

examplereseller@partner.com

Reseller email address, in case the agent is created by a reseller party

visual_design

object

tagline

string

Required

Max100

exampleYour trusted banking assistant

Short tagline describing the agent or brand

brand_color

string

Required

example#FF5733

Brand color in hex format, used for button text and UI elements above the agent phone number. Must meet a minimum contrast ratio of 4.5:1 against white (WCAG 2.0). See the support article

logo_image

string

examplehttps://cdn.example.com/logo.png

URL of the agent logo image. Shown as a circular avatar next to messages. Requirements: JPEG or PNG, 224x224 px, max 50 KB. See the support article

banner_image

string

examplehttps://cdn.example.com/banner.png

URL of the agent banner image. Displayed as a header when users view the agent business info. Requirements: JPEG, 1440x448 px, max 200 KB. See the support article

phone

array

Required

List of phone contact numbers (1-3)

number

string

Required

example+12025551234

Phone number in E.164 format

label

string

Max25

exampleCustomer Support

Display label for this phone number

array

Required

List of email contact addresses (1-3)

address

string

Required

Min1

examplesupport@example.com

Email address

label

string

Max25

exampleCustomer Support

Display label for this email address

website

array

Required

List of website links (1-3)

url

string

Required

examplehttps://www.example.com

Website URL

label

string

Max25

exampleOfficial Website

Display label for this website

privacy_policy

string

examplehttps://www.example.com/privacy

URL of the privacy policy

terms_of_service

string

examplehttps://www.example.com/terms

URL of the terms of service

application_settings

object

application_id

string

Required

examplea1b2c3d4-e5f6-7890-abcd-ef1234567890

Vonage application ID to associate with this agent

test_devices

array

string(uuid)

Required

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Unique test device identifier

phone

string

Required

example+12025551234

Phone number of the test device in E.164 format

created_at

string

Required

Date and time when the test device was added

status

string

Required

exampleACTIVE

Status of the test device registration

representative

object

first_name

string

Required

Max200

exampleJane

First name of the authorized representative

last_name

string

Required

Max200

exampleDoe

Last name of the authorized representative

title

string

Max200

exampleHead of Messaging

Job title of the authorized representative

string

Required

examplejane.doe@example.com

Email address of the authorized representative

brand_website

string

examplehttps://www.example.com

Brand website URL

phone

string

example+12025551234

Phone number in E.164 format

carrier_requirements

object

version

string

Required

examplev2

Carrier requirements schema version

points_of_contact

array

first_name

string

Required

Max200

exampleJohn

The first name of the point of contact for the RCS Agent.

last_name

string

Required

Max200

exampleDoe

The last name of the point of contact for the RCS Agent.

job_title

string

Required

Max200

exampleHead of Messaging

The job title of the point of contact for the RCS Agent.

string

Required

examplejohn.doe@example.com

The email address of the point of contact for the RCS Agent.

phone

string

example+12025551234

The phone number of the point of contact for the RCS Agent.

agent_preview

object

Required

agent_access_instructions

string

Required

Max10000

exampleVisit https://example.com/rcs-agent and follow the onboarding flow.

Instructions for reviewers on how to access and test the agent

urls

array

List of media URLs showcasing the agent (up to 10)

media_type

string

Required

exampleimage

Media type of the preview asset

Must be one of:imagevideo

url

string

Required

examplehttps://cdn.example.com/preview.png

URL of the preview asset

rcs_agent_discovery_methods

object

selection

array

Required

Methods through which users discover the RCS agent

other_input

string

Max500

examplePromoted via in-store QR codes

Additional details when OTHER is selected

consent_management

object

Required

user_messaging_consent_methods

object

Required

selection

array

Required

Selected consent methods

other_input

string

Max500

exampleUsers consent via in-store sign-up forms

Additional details when OTHER is selected

users_opt_in_process

object

Required

selection

array

Required

Selected opt-in methods

links

array

URLs where users can opt in (up to 10)

first_opt_in_message

string

Required

Max1000

exampleWelcome! You have successfully opted in to receive updates from Acme Bank.

The first message sent to users after opting in

users_opt_out_methods

object

Required

selection

array

Required

Selected opt-out methods

other_input

string

Max500

exampleUsers can opt out via the account settings page

Additional details when OTHER is selected

opt_out_processing_time

object

Required

selection

string

Required

exampleWITHIN_5_MINUTES

How quickly opt-out requests are processed

Must be one of:WITHIN_5_MINUTESWITHIN_24_HOURSOTHER

other_input

string

Max500

exampleProcessed within 2 business days

Additional details when OTHER is selected

opt_out_confirmation_message

object

Required

selection

string

Required

exampleSUCCESSFULLY_UNSUBSCRIBED

Confirmation message template sent after opt-out

Must be one of:SUCCESSFULLY_UNSUBSCRIBEDWONT_RECEIVE_FURTHER_MESSAGESOPT_OUT_REQUEST_PROCESSEDREPLY_START_TO_RESUBSCRIBEOPT_OUT_CONFIRMEDOTHER

other_input

string

Max500

exampleYou have been unsubscribed. Contact support@example.com to resubscribe.

Additional details when OTHER is selected

cta_language

string

Min1

Max2000

exampleReply YES to receive exclusive offers from Acme Bank.

Call-to-action language used in consent flows

engagement_flows

object

Required

agent_description

string

Required

Max5000

exampleAcme Bank RCS agent helps customers check balances, receive transaction alerts, and manage payments.

Description of what the agent does and how it engages with users

reasons_messages_sent

object

Required

Reasons why messages are sent to users

selection

array

Required

Selected reasons for sending messages

other_input

string

Max500

exampleSending loyalty program milestone notifications

Additional details when OTHER is selected

monthly_user_message_count

string

Required

exampleTHREE_FIVE_MESSAGES

Estimated number of messages sent to each user per month

Must be one of:ONE_TWO_MESSAGESTHREE_FIVE_MESSAGESSIX_TEN_MESSAGESELEVEN_TWENTY_MESSAGESMORE_THAN_TWENTY_ONE_MESSAGES

rcs_user_interaction_types

object

Required

Types of interactions users have with the agent

selection

array

Required

Selected types of RCS user interactions

other_input

string

Max500

exampleUsers interact via custom carousels

Additional details when OTHER is selected

help_interaction

string

Min1

Max2000

exampleReply HELP for assistance or visit https://www.example.com/support

How the agent responds to HELP messages from users

message_samples

array

Sample messages the agent will send to users (3-10 samples required)

message_type

string

exampleRICH_MEDIA

Type of RCS messages the agent sends. Use RICH_TEXT or RICH_MEDIA for US carriers; BASIC or SINGLE for non-US carriers.

Must be one of:RICH_TEXTRICH_MEDIABASICSINGLE

agent_summary

object

program_summary

string

Min1

Max2000

exampleAcme Bank sends transactional alerts and OTP messages to account holders who have opted in.

Summary of the agent messaging program and its intended use

current_traffic

object

organic_website_traffic

object

Current organic website traffic range

min

integer(int64)

max

integer(int64)

existing_shortcode_traffic

boolean

exampletrue

Whether the brand currently uses a shortcode for messaging

shortcode_monthly_traffic

object

Monthly traffic volume range for the existing shortcode

min

integer(int64)

max

integer(int64)

shortcode

string

Max50

example12345

Existing shortcode number

carriers

array

string

Required

examplegoogle-us-att

Carrier identifier

launch_state

string

Current launch state for this carrier

update_time

string

Date and time of the last status update

launch_submitted_at

string

Date and time when the launch was submitted for this carrier

comment

string

Comment or reason associated with the current launch state

verification_details

object

status

string

exampleVERIFICATION_STATE_VERIFIED

Verification status of the agent

Must be one of:VERIFICATION_STATE_UNSPECIFIEDVERIFICATION_STATE_UNVERIFIEDVERIFICATION_STATE_PENDINGVERIFICATION_STATE_VERIFIED

brand_details

object

organization_name

string

Required

Max255

legal_form

string

Required

Max50

stock_symbol

string

Max12

legal_entity_type

string

Required

Max50

country_of_registration

string

Required

Min2

Max2

federal_tax_id

string

Max50

business_website_url

string

Required

Max255

address_line1

string

Required

Max255

address_line2

string

Max255

city

string

Required

Max100

state_or_province

string

Required

Max100

zip_or_post_code

string

Required

Max15

launch_submitted_at

string

Date and time when the agent launch was submitted

created_at

string

Date and time when the agent was created

updated_at

string

Date and time when the agent was last updated

Example Response

Get Carriers

Retrieve a list of available carriers for RCS.

gethttps://api.nexmo.com/v2/channel-manager/rcs/metadata/carriers

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

carriers

array

Required

A list of available carriers for RCS.

string

Required

exampleverizon-us

A unique identifier for the carrier.

carrier

string

Required

exampleVerizon

The name of the carrier.

country_letter_code

string

Required

exampleUS

Code for the country where the carrier operates.

Example Response

Add Carriers to Agent

Add carriers to an existing RCS Agent.

posthttps://api.nexmo.com/v2/channel-manager/rcs/agents/:agent_id/carriers

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

agent_id

string

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

Agent ID

Request Body
Content Type
application/json

carriers

array

Required

An array of Carrier IDs to add to the RCS Agent.

Example Request

Responses
Content Type
application/json

Accepted

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

message

string

Required

exampleRequest accepted for processing

Example Response

Launch RCS Agent

Launch an existing RCS Agent

posthttps://api.nexmo.com/v2/channel-manager/rcs/agents/:agent_id/launch

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

agent_id

string

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

Agent ID

Responses
Content Type
application/json

Accepted

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

message

string

Required

exampleRequest accepted for processing

Example Response

Add Test Devices to Agent

Add test devices to an existing RCS Agent.

posthttps://api.nexmo.com/v2/channel-manager/rcs/agents/:agent_id/test-devices

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

agent_id

string

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

Agent ID

Request Body
Content Type
application/json

phone

string

Required

example+14155552671

The phone number to add to the RCS Agent in E.164 format.

Example Request

Responses
Content Type
application/json

Accepted

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string(uuid)

Required

example0198ecd4-da21-7f8b-91d8-ccfbaec485a7

Unique test device identifier

phone

string

Required

example+12025551234

Phone number of the test device in E.164 format

created_at

string

Required

Date and time when the test device was added

status

string

Required

exampleACTIVE

Status of the test device registration

Example Response

Remove Test Device from Agent

Remove a test device from an existing RCS Agent.

deletehttps://api.nexmo.com/v2/channel-manager/rcs/agents/:agent_id/test-devices/:test_device_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

agent_id

string

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

Agent ID

test_device_id

string

Required

example019809ba-a274-7bd2-aea0-f1f70f2210dc

Test Device Id

Responses

No Content - Resource successfully deleted

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

RCS Deeplinks

API endpoints relating to generating RCS Deeplinks

Available Operations

Generate RCS Deeplink

Generate RCS Deeplink

Generate an RCS deeplink for a specific RCS agent and use case. See the RCS Deeplinks documentation for more information.

posthttps://api.nexmo.com/v1/channel-manager/rcs/deeplink/generate

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Request Body
Content Type
application/json

sender_id

string

Required

Max50

exampleacme_agent

Messages API sender ID (a.k.a. external ID) that identifies the RCS agent.

country

string

Required

Min2

Max2

exampleUS

ISO 3166-1 alpha-2 country code of the country where the deep link will operate.

prefilled_message

string

Max3072

exampleI'm interested in finding out about your new product. Please send me more details.

Optional pre-defined message that will be populated in the send-message dialog of the SMS/RCS app on the end user's device when the user opens the deep link.

fallback_number

string

example+15550123456

Optional Vonage virtual number in E.164 format that will be used as the SMS fallback destination if the end user's device does not support RCS.

Example Request

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

deep_link

string(uri)

Required

examplehttps://tools.vonage.com/rcs/v1/deeplink/jNiLGT29KY4RVzTczcA83NFFhv28Ut-bdnutpcG8OTv-7a8vt75f3ka1eyDh3L4KZTkJ9qgXHk

The generated RCS deeplink URL.

Channel Manager API

WhatsApp WABAs

Available Operations

List WhatsApp Business Accounts (WABAs)

Authentication

Query Parameters

Responses Content Typeapplication/json

Header Parameters

Example Response

Get a specific WhatsApp Business Account (WABA)

Authentication

Path Parameters

Responses Content Typeapplication/json

Header Parameters

Example Response

List Numbers for a WhatsApp Business Account (WABA)

Authentication

Path Parameters

Query Parameters

Responses Content Typeapplication/json

Header Parameters

Example Response

Get a specific WhatsApp Business Account (WABA) Number

Authentication

Path Parameters

Responses Content Typeapplication/json

Header Parameters

Example Response

Get the profile for a specific WhatsApp Business Account (WABA) Number

Authentication

Path Parameters

Responses Content Typeapplication/json

Header Parameters

Example Response

Update the profile for a specific WhatsApp Business Account (WABA) Number

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Header Parameters

Example Response

WhatsApp Hosted ES Flow

Available Operations

Generate Hosted ES Flow URL

Authentication

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Header Parameters

Example Response

WhatsApp Analytics

Available Operations

Get Template Analytics

Authentication

Path Parameters

Query Parameters

Responses Content Typeapplication/json

Header Parameters

Example Response

Get Messaging Analytics

Authentication

Path Parameters

Query Parameters

Responses Content Typeapplication/json

Header Parameters

Example Response

Get Pricing Analytics

Authentication

Path Parameters

Query Parameters

Responses Content Typeapplication/json

Header Parameters

Example Response

Enable template analytics

Authentication

Path Parameters

Responses

Header Parameters

WhatsApp Notification Subscriptions

Responses
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json