Create an RCS Agent

post

https://api.liguelead.com.br/v1/rcs/agents

Registers the sender brand and hands it over for review in one call.

Every brand field is required. There is no draft here: an integration assembles the whole form and sends it once, so a missing field answers 422 naming what is absent, before anything is created. test_devices is the only optional field.

The registration comes back as submitted. Follow it through the rcs.agent.status webhook sent to the agent's webhook_url, or with GET /v1/rcs/agents/{id}.

An app can hold more than one agent, typically one per use_case, and each template belongs to one of them. To change a registration, use PUT; to give up on it, DELETE.

Images are referenced by public URL; we do not accept file uploads here.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Fields of a new registration. All of them are required: a registration is opened complete, and PUT /rcs/agents/{id} replaces it afterwards — see RcsAgentUpdate, where only use_case is optional.

The app is not one of them: the registration is bound to the app your credentials resolve to, taken from the app-id header, exactly as the client is. There is one app per credential pair, so there is nothing to choose — and choosing would let one app register a brand that goes out under another.

Any field outside this list is rejected with 422 rather than ignored — app_id and app_ids included, alongside status, approved and the supplier identifiers, which are ours to set. A silent drop would leave you believing otherwise.

webhook_url

uri | null

Where this registration's review notifications go — the rcs.agent.status event, fired when the brand is picked up for review, approved or rejected.

It is the agent's own address, not the app's. The webhook URL configured for your app carries campaign events: delivery status and reply-button postbacks. A brand review happens before any of that and usually belongs to a different system of yours, so it is declared here and arrives there alone.

Optional. An agent without it is never notified, and nothing falls back to the app's URL. GET /rcs/agents/{id} still answers the state at any time.

use_case

string

enum

required

What the brand is for. The carrier homologates the agent against this and suspends whoever leaves it — a verification-code agent sending marketing takes the channel down in days. It also decides which of the supplier's projects the brand is registered in. It does not change after approval: the brand is registered in that project at the supplier, so changing the purpose means registering again.

Allowed:

sender_name

string

required

length ≤ 100

Name shown on the recipient's device. Up to 100 characters.

sender_description

string

required

length ≤ 500

Short description shown alongside the name. Up to 500 characters.

brand_color

string

required

^#[0-9a-fA-F]{6}$

Brand colour in #RRGGBB. Any other format is rejected. It is painted behind white text on the device, so the carrier requires a contrast ratio of at least 4.5:1 against white — a pale colour passes this call and is refused during the review.

logo_url

uri

required

length ≤ 2048

Public URL of the logo. You host the file; we do not accept uploads on this endpoint. The carrier requires a square image of 224×224 pixels, up to 50 KB, in JPEG or PNG — anything else is refused during the review, not on this call.

banner_url

uri

required

length ≤ 2048

Public URL of the banner. Same rule as the logo, with the carrier asking for 1440×448 pixels, up to 200 KB.

contact_name

string

required

length ≤ 255

Person responsible for the registration. Not shown to recipients — we use it to reach you during the review.

contact_email

string

required

length ≤ 255

E-mail of the person responsible. Not shown to recipients.

company_name

string

required

length ≤ 255

Trading name of the company.

legal_name

string

required

length ≤ 255

Registered legal name, as it appears on the company records.

company_website

uri

required

length ≤ 2048

Corporate website. The carrier checks the brand against it.

phone

string

required

length ≤ 20

Public phone number shown to the recipient.

public_email

string

required

length ≤ 255

Public e-mail shown to the recipient.

public_website

uri

required

length ≤ 2048

Public website shown to the recipient.

privacy_policy_url

uri

required

length ≤ 2048

terms_url

uri

required

length ≤ 2048

test_devices

array of strings

length ≤ 20

Phone numbers allowed to receive the agent before it is approved, so you can see the brand on a real device. Not required to submit. Up to 20 numbers.

test_devices

Responses

Callback

201Registration created.

401api-token or app-id missing, invalid or blocked.

422A field failed validation, or an unexpected field was sent.