Como enviar mensagens de texto RCS com o Go e a Messages API do Vonage

RCS (Rich Communication Services) leva o SMS a um novo patamar com mensagens interativas, imagens, mídia avançada, confirmações de leitura e muito mais. Este tutorial mostrará como enviar mensagens de texto RCS básicas usando Go e a Messages API do Vonage, além de estabelecer as bases para recursos mais avançados.

>> Resumo: Encontre o no GitHub.

Embora o SDK do Vonage Go esteja atualmente arquivado, podemos usar solicitações diretas à API por meio de net/http, o que lhe dá controle total sobre a solicitação e a resposta.

Pré-requisitos

Certifique-se de ter o seguinte:

• Ir 1.18+ instalado

• Um Account da API da Vonage 

• Um agente registrado do RCS Business Messaging (RBM)

• Um celular com o RCS ativado para testes

• ngrok (para testes de webhooks locais — opcional neste exemplo)

Como entrar em contato com o seu gerente de account da Vonage

Para enviar e receber mensagens com recursos RCS no seu aplicativo da Vonage, você precisará ter um agente Rich Business Messaging (RBM) registrado e um telefone com recursos RCS.

Atualmente, o serviço de mensagens RCS via Vonage está disponível apenas para contas gerenciadas. Você precisará entrar em contato com seu gerente de conta para solicitar a ativação do Modo Desenvolvedor para o seu agente RBM. O Modo Desenvolvedor permite que você teste o envio de mensagens RCS para números incluídos na lista de permissões antes de concluir o processo de verificação do agente e iniciar a operação em produção.

Por favor, entre em contato com nossa equipe de vendas caso você não tenha um account gerenciado.

Como configurar seu projeto de Go

Vamos começar configurando nosso projeto.

Inicializar o projeto

Crie um novo diretório e inicialize um módulo Go:

mkdir rcs-text-golang
cd rcs-text-golang
go mod init rcs-text-golang

Instalar as dependências do projeto

Instale os pacotes Go necessários:

go get github.com/joho/godotenv github.com/golang-jwt/jwt/v4

• godotenv: Carrega variáveis de ambiente a partir de um arquivo .env

• golang-jwt: É responsável pela geração de tokens JWT para autenticação na API

Crie os arquivos do seu projeto

Crie o arquivo principal do aplicativo e o arquivo de configuração do ambiente:

touch main.go .env

Como configurar variáveis de ambiente

No arquivo .env, adicione suas credenciais e configuração do Vonage:

RCS_SENDER_ID=""
TO_NUMBER=""
VONAGE_PRIVATE_KEY_PATH=./private.key
VONAGE_APPLICATION_ID=""

• RCS_SENDER_ID: Seu SenderID do RBM (o nome da marca). O SenderID deve seguir uma formatação específica, como, por exemplo, não conter espaços. Se tiver dúvidas, consulte seu gerente de Account.

• TO_NUMBER: O número de telefone do destinatário no formato internacional, sem o símbolo + (por exemplo, 447700900000)

• VONAGE_PRIVATE_KEY_PATH: Caminho para o arquivo da sua chave privada

• VONAGE_APPLICATION_ID: Seu ID de inscrição na Vonage

Você obterá seu ID de aplicativo da Vonage e o arquivo private.key na seção “Como criar e configurar seu aplicativo da Vonage”, abaixo.

Como enviar mensagens de texto RCS

Nesta main.go, vamos implementar a funcionalidade para enviar mensagens de texto RCS usando a Messages API do Vonage.

Definir a estrutura da mensagem RCS

Primeiro, vamos definir a estrutura da nossa mensagem RCS:

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"

	"github.com/golang-jwt/jwt/v4"
	"github.com/joho/godotenv"
)

type RCSMessage struct {
	From        string `json:"from"`
	To          string `json:"to"`
	Channel     string `json:"channel"`
	MessageType string `json:"message_type"`
	Text        string `json:"text"`
}

Essa estrutura utiliza os campos mínimos obrigatórios. Para conhecer todos os recursos das mensagens RCS, incluindo o failover para SMS, consulte a Referência da API de Envio de Mensagens.

Implementar a função principal

Agora, vamos implementar a função principal para enviar a mensagem RCS. A função principal pode ser dividida em três partes principais:

• Instalação e configuração: A função carrega as variáveis de ambiente do arquivo .env, recupera configurações essenciais, como o ID do remetente e o número do destinatário, e cria uma estrutura de mensagem RCS com o conteúdo de texto.

• Autenticação e preparação da solicitação: Ele gera um token JWT usando o ID do aplicativo e a chave privada e, em seguida, cria uma solicitação HTTP com a carga útil da mensagem e os cabeçalhos de autorização adequados.

• Execução da solicitação e tratamento da resposta: A função envia a solicitação HTTP para a Messages API do Vonage, processa a resposta e exibe tanto o código de status quanto o corpo da resposta para confirmar que a mensagem foi entregue com sucesso.

func main() {
	err := godotenv.Load()
	if err != nil {
		fmt.Println("Error loading .env file")
		os.Exit(1)
	}
	
	fromID := os.Getenv("RCS_SENDER_ID")
	toNumber := os.Getenv("TO_NUMBER")
	applicationID := os.Getenv("VONAGE_APPLICATION_ID")
	privateKeyPath := os.Getenv("VONAGE_PRIVATE_KEY_PATH")

	if applicationID == "" || privateKeyPath == "" || fromID == "" || toNumber == "" {
		fmt.Println("Error: Required environment variables are missing.")
		os.Exit(1)
	}

	message := RCSMessage{
		From:        fromID,
		To:          toNumber,
		Channel:     "rcs",
		MessageType: "text",
		Text:        "Hello from Go and Vonage!",
	}

	payload, err := json.Marshal(message)
	if err != nil {
		fmt.Println("Error encoding JSON:", err)
		return
	}

	req, err := http.NewRequest("POST", "https://api.nexmo.com/v1/messages", bytes.NewBuffer(payload))
	if err != nil {
		fmt.Println("Error creating request:", err)
		return
	}

	token, err := generateJWT(applicationID, privateKeyPath)
	if err != nil {
		fmt.Println("Error generating JWT:", err)
		return
	}
	
	req.Header.Add("Authorization", "Bearer "+token)
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Accept", "application/json")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println("Error sending request:", err)
		return
	}
	defer resp.Body.Close()

	fmt.Printf("Response status: %s\n", resp.Status)
	
	var respBody bytes.Buffer
	_, err = respBody.ReadFrom(resp.Body)
	if err != nil {
		fmt.Println("Error reading response body:", err)
		return
	}
	
	fmt.Println("Response body:", respBody.String())
}

Implementar a autenticação JWT

A função principal depende de uma generateJWT função para passar a autenticação JWT para a Messages API. Vamos implementar a função para gerar um token JWT:

func generateJWT(applicationID, privateKeyPath string) (string, error) {
	privateKeyBytes, err := os.ReadFile(privateKeyPath)
	if err != nil {
		return "", fmt.Errorf("error reading private key: %w", err)
	}
	
	privateKey, err := jwt.ParseRSAPrivateKeyFromPEM(privateKeyBytes)
	if err != nil {
		return "", fmt.Errorf("error parsing private key: %w", err)
	}
	
	claims := jwt.MapClaims{
		"application_id": applicationID,
		"iat":           time.Now().Unix(),
		"exp":           time.Now().Add(time.Hour).Unix(),
		"jti":           time.Now().UnixNano(),
	}
	
	token := jwt.NewWithClaims(jwt.SigningMethodRS256, claims)
	
	tokenString, err := token.SignedString(privateKey)
	if err != nil {
		return "", fmt.Errorf("error signing token: %w", err)
	}
	

>> Veja o arquivo main.go .

Como criar e configurar seu aplicativo da Vonage

Agora que seu aplicativo Go está pronto, você também precisará criar e configurar seu aplicativo Vonage:

Crie seu aplicativo no Painel da Vonage. Dê um nome ao aplicativo e ative o recurso “Mensagens”.

Nas configurações do seu aplicativo Vonage:

• Defina a URL de entrada como um endpoint de webhook (você pode usar o ngrok para testes)

• Defina a URL de status para receber atualizações sobre o status das mensagens

• Gere uma chave pública e uma chave privada clicando no botão

  • Certifique-se de mover o arquivo private.key para o diretório raiz do projeto ( rcs-text-golang )

• Salvar as alterações

Em seguida, vincule seu RCS Agent clicando na guia “Vincular contas externas”:

Vonage application dashboard showing successful linking of an RCS external account to a Go-based application.

Como testar seu aplicativo Go RCS

Execute seu aplicativo Go:

go run main.go

Se tudo estiver configurado corretamente, você deverá ver uma resposta indicando sucesso:

Response status: 202 Accepted
Response body: {"message_uuid":"83e829db-8784-40a1-bfd6-26399046d4d2"}

No dispositivo do destinatário compatível com RCS, a mensagem deve aparecer no aplicativo de mensagens nativo com o nome da sua marca e o conteúdo da mensagem.

RCS message received from a Vonage agent using Go and the Messages API.

Considerações finais

Ótimo trabalho! Você implementou com sucesso o envio de mensagens de texto RCS usando Go e a Messages API do Vonage. Mas o RCS oferece muito mais! Você pode tentar enviar respostas sugeridas, imagens em alta resolução e Videos, ou os Rich Cards específicos do RCS.

A Messages API também fornece status das mensagens, o que nos ajuda a entender o que está acontecendo com nossas mensagens RCS. Em uma futura postagem no blog, mostrarei como acompanhar os status das mensagens usando webhooks.

Se você tiver alguma dúvida ou sugestão para mais conteúdos sobre Go ou RCS, participe da conversa conosco no Slack da Comunidade Vonage ou entre em contato pelo X, antes conhecido como Twitter. Adoraríamos saber o que você vai criar a seguir!