RCS Brand and Agent Builder utilizando a API do Channel Manager
Para utilizar a oferta de RCS da Vonage, uma marca precisa registrar alguns metadados no nível da marca, criar um Agente que represente a marca no RCS, submetê-lo à verificação e, em seguida, utilizá-lo na Messages API ao enviar mensagens RCS. A API do Gerenciador de Canais fornece pontos de extremidade para gerenciar essas entidades (Marca, Agente) programaticamente.
Este guia explica como:
- Quais são os pré-requisitos que devem ser atendidos?
- Os endpoints de gerenciamento de marca: o que fazem e quais dados são necessários.
- Os endpoints de gerenciamento de agentes: para que servem e quais dados são necessários.
- O fluxo de trabalho completo de integração: etapas e transições de status.
Pré-requisitos
Antes de começar a usar os endpoints da API, certifique-se de que:
- Você possui um account na API da Vonage.
- Você está autorizado a acessar as APIs de Gestão de Marcas e de Gestão de Agentes.
- Você reuniu todos os metadados necessários sobre a marca/agente: nome da marca, logotipo, imagem de banner, site, política de privacidade, termos de serviço, informações de e-mail/exibição, etc.
- Você conhece os requisitos de verificação no território-alvo (por exemplo, nos EUA).
Principais componentes da API
Existem duas entidades principais:
- Marca: representa sua organização (empresa, identidade da marca).
- Agente: representa a identidade da marca ao enviar mensagens (nome, logotipo, cor etc.).
Pontos-chave da gestão de marcas
Essas interfaces de API são utilizadas para criar ou atualizar a entidade “Marca”.
| Operação | Método e caminho HTTP | Objetivo |
|---|---|---|
| Lista de marcas | [OBTER] https://api.nexmo.com/v1/channel-manager/rcs/brands |
Liste todas as marcas do seu Account. |
| Criar marca | POST https://api.nexmo.com/v1/channel-manager/rcs/brands |
Crie uma nova marca. |
| Atualizar marca | PATCH https://api.nexmo.com/v1/channel-manager/rcs/brands/:brand_id |
Alterar o nome da marca. |
| Excluir marca | [EXCLUIR] https://api.nexmo.com/v1/channel-manager/rcs/brands/:brand_id |
Excluir uma marca RCS existente. |
Pontos de extremidade de gerenciamento de agentes
Esses endpoints são usados para criar agentes sob uma marca. Um agente é o que é necessário para enviar mensagens RCS em nome da marca.
| Operação | Método e caminho HTTP | Objetivo |
|---|---|---|
| Lista de corretores | [OBTER] https://api.nexmo.com/v1/channel-manager/rcs/agents |
Liste todos os agentes vinculados à sua Account ou a uma marca. |
| Criar agente | POST https://api.nexmo.com/v1/channel-manager/rcs/agents |
Registrar um agente para uma determinada marca, incluindo o fornecimento de recursos de identidade visual (logotipo, banner), informações de exibição, número de telefone, descrição etc. |
| Obter agente | [OBTER] https://api.nexmo.com/v1/channel-manager/rcs/agents/:agent_id |
Recupere os metadados do agente, seu status, a marca associada, etc. |
| Agente de Atualização | PUT https://api.nexmo.com/v1/channel-manager/rcs/agents/:agent_id |
Altere os metadados do agente de mudança, as imagens, eventualmente o número de telefone e a descrição. Alguns campos podem ficar bloqueados após a verificação. |
| Agente de atualização parcial | PATCH https://api.nexmo.com/v1/channel-manager/rcs/agents/:agent_id |
Atualizar parcialmente um Agente RCS existente. |
| Ver operadoras | [OBTER] https://api.nexmo.com/v1/channel-manager/rcs/metadata/carriers |
Recupere a lista de transportadoras. |
| Adicionar operadoras ao agente | POST https://api.nexmo.com/v1/channel-manager/rcs/agents/:agent_id/carriers |
Adicionar operadoras a um Agente RCS já existente. |
| Adicionar dispositivos de teste ao agente | POST https://api.nexmo.com/v1/channel-manager/rcs/agents/:agent_id/test-devices |
Adicionar dispositivos de teste a um Agente RCS já existente. |
| Remover o dispositivo de teste do agente | [EXCLUIR] https://api.nexmo.com/v1/channel-manager/rcs/agents/:agent_id/test-devices/:test_device_id |
Remover um dispositivo de teste de um Agente RCS existente. |
Fluxo de trabalho de integração
Este é o fluxo típico de integração para configurar os endpoints da Marca e do Agente:
Comece criando uma marca com o POST /v1/channel-manager/rcs/brands endpoint. Nessa solicitação, você registra o nome da sua marca. Assim que a marca for criada, a API retorna um brand_id que você deve consultar em todas as etapas seguintes.
Quando a marca existe, você cria um agente chamando o POST /v1/channel-manager/rcs/agents ponto de extremidade. O agente representa o perfil voltado para o cliente que enviará mensagens RCS em nome da sua marca. Nesta solicitação, você fornece o brand_id juntamente com o nome de exibição, a descrição, as imagens e os dados de contato do agente. A API responde com um agent_id, que passa a ser o identificador de todas as operações realizadas no agente.
Adicione números de teste usando o POST https://api.nexmo.com/v1/channel-manager/rcs/agents/:agent_id/test-devices ponto final. Esses números permitem que você teste a experiência do agente antes de colocá-la em operação.
Inicie o agente usando PUT /v1/channel-manager/rcs/agents/:agent_id ou usando PATCH /v1/channel-manager/rcs/agents/:agent_id e fornecendo informações relevantes.
Observação: só é possível editar o agente até que ele seja lançado. Após o lançamento, entre em contato com seu gerente de Account ou com o Suporte da Vonage para quaisquer edições adicionais.
Selecione as operadoras que devem hospedar o agente chamando o POST /v1/channel-manager/rcs/agents/{agentId}/carriers ponto final. Nessa solicitação, você especifica a lista de IDs de operadoras nas quais deseja que o agente seja iniciado. Você pode verificar a configuração da operadora com GET /v1/channel-manager/rcs/carriers.
Quando as operadoras e o Google aprovam o agente, isso não faz com que ele fique disponível imediatamente em produção. Em vez disso, a solicitação é encaminhada para uma análise interna por nossa equipe de operações, que trabalhará com as operadoras para concluir o lançamento. O processo geralmente leva de 4 a 8 semanas; após esse período, você poderá começar a usar o agente como remetente na Messages API para enviar mensagens RCS aos seus clientes.
Manutenção contínua
Se algum metadado precisar ser atualizado (logotipo, descrição), verifique quais campos podem ser editados após a verificação ou entre em contato com seu gerente de Account. Alguns podem estar bloqueados.
Status dos agentes
| Status | Descrição |
|---|---|
| DRAFT | Status temporário por um breve período após o envio das informações do agente, enquanto os processos de back-end são iniciados. O registro do agente está incompleto nessa fase. |
| CREATED | O registro do agente está completo e armazenado com segurança no sistema. |
| PENDING | O agente foi enviado para verificação. As operadoras e o Google estão analisando a marca. O agente permanecerá indisponível para lançamento até que seja aprovado em todas as verificações. |
| REJECTED | O agente não passou no processo de verificação e não pode ser iniciado. |
| LAUNCHED | O agente passou em todas as verificações e recebeu aprovação das operadoras e do Google. Agora ele está ativo e pode ser usado como remetente na Messages API para conversas RCS. |
Leitura complementar
Guia do RCS Agent Builder
Referência da API do Channel Manager