Cómo enviar mensajes de texto RCS con Go y la API Messages API de Vonage

RCS (Servicios de Comunicación Enriquecidos) lleva los SMS al siguiente nivel con mensajes interactivos, imágenes, medios enriquecidos, recibos de lectura y más. Este tutorial te mostrará cómo enviar mensajes de texto RCS básicos usando Go y Messages API de Vonage y sentará las bases para funciones más avanzadas.

>> TL;DR: Encuentra el código completo en GitHub.

Aunque el Vonage Go SDK está actualmente archivado, podemos utilizar solicitudes directas a la API a través de net/httplo que te da control total sobre la solicitud y la respuesta.

Requisitos previos

Asegúrate de tener lo siguiente:

• Ir a 1.18+ instalado

• Una cuenta API de Vonage

• Un agente registrado de RCS Business Messaging (RBM)

• Un teléfono con RCS activado para las pruebas

• ngrok (para pruebas locales de webhook - opcional en este ejemplo)

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Cómo contactar a tu administrador de cuentas de Vonage

Para poder enviar y recibir funciones RCS en tu aplicación de Vonage, deberás tener un agente registrado de Rich Business Messaging (RBM) y un teléfono con capacidades de RCS.

Actualmente, la mensajería RCS a través de Vonage sólo está disponible para cuentas administradas. Deberás comunicarte con tu administrador de cuenta para solicitar la activación del modo para desarrolladores para tu agente de RBM. El modo para desarrolladores te permite probar la mensajería RCS a números permitidos antes de completar el proceso de verificación del agente y lanzarlo en producción.

Por favor póngase en contacto con nuestro equipo de ventas si no tiene una cuenta gestionada.

Cómo configurar su proyecto Go

Empecemos por configurar nuestro proyecto.

Inicializar el proyecto

Crea un nuevo directorio e inicializa un módulo Go:

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

Instalar dependencias del proyecto

Instale los paquetes Go necesarios:

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

• godotenv: Carga variables de entorno desde un archivo .env

• golang-jwt: Gestiona la generación de tokens JWT para la autenticación de la API.

Cree sus archivos de proyecto

Cree el archivo principal de la aplicación y el archivo de configuración del entorno:

touch main.go .env

Cómo configurar las variables de entorno

En el archivo .env, agrega tus credenciales y configuración de Vonage:

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

• RCS_SENDER_ID: Su RBM SenderID (el nombre de la marca). El SenderID requiere un formato especial, como no tener espacios. Consulte con su Account Manager si no está seguro.

• TO_NUMBER: El número de teléfono del destinatario en formato internacional sin el símbolo + (por ejemplo, 447700900000).

• VONAGE_PRIVATE_KEY_PATH: Ruta a su archivo de clave privada

• VONAGE_APPLICATION_ID: Tu ID de aplicación de Vonage

Obtendrás tu ID de aplicación de Vonage y el archivo private.key en la sección "Cómo crear y configurar tu aplicación de Vonage" a continuación.

Cómo enviar mensajes de texto RCS

En main.govamos a implementar la funcionalidad para enviar mensajes de texto RCS utilizando la API Messages API de Vonage.

Definir la estructura del mensaje RCS

En primer lugar, vamos a definir la estructura de nuestro mensaje 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"`
}

Esta estructura utiliza los campos mínimos requeridos. Para ver todas las capacidades de los mensajes RCS, incluida la conmutación por error de SMS, puede consultar la Referencia de la API de envío de mensajes.

Implementar la función principal

Ahora, implementemos la función principal para enviar el mensaje RCS. La función principal se puede dividir en tres partes clave:

• Instalación y configuración: La función carga las variables de entorno desde el archivo .env, recupera la configuración crítica como el ID de remitente y el número de destinatario, y crea una estructura de mensaje RCS con el contenido del texto.

• Autenticación y preparación de solicitudes: Genera un token JWT utilizando el ID de la aplicación y la clave privada y, a continuación, crea una solicitud HTTP con la carga útil del mensaje y las cabeceras de autorización adecuadas.

• Ejecución de solicitudes y gestión de respuestas: La función envía la solicitud HTTP a la API de Messages API de Vonage, procesa la respuesta y muestra tanto el código de estado como el cuerpo de la respuesta para confirmar la entrega exitosa del mensaje.

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 la autenticación JWT

La función principal se basa en una función generateJWT para pasar la autenticación JWT para la Messages API. Vamos a implementar la función para generar un 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)
	}
	

>> Ver el archivo main.go completo.

Cómo crear y configurar tu aplicación de Vonage

Ahora que tu aplicación Go está lista, también deberás crear y configurar tu aplicación de Vonage:

Crea tu aplicación en el panel de Vonage. Dale un nombre a la aplicación y activa la función Mensajes.

En la configuración de tu aplicación de Vonage:

• Establezca la URL de entrada a un punto final de webhook (puede utilizar ngrok para realizar pruebas)

• Establezca la URL de estado para recibir actualizaciones del estado de los mensajes

• Genere una clave pública y privada pulsando el botón

  • Asegúrese de mover su archivo private.key al directorio raíz del proyecto ( rcs-text-golang )

• Guardar los cambios

A continuación, vincule su Agente RCS haciendo clic en la pestaña "Vincular cuentas externas":

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

Cómo probar su aplicación Go RCS

Ejecute su aplicación Go:

go run main.go

Si todo está configurado correctamente, debería ver una respuesta satisfactoria:

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

En el dispositivo habilitado para RCS del destinatario, el mensaje debería aparecer en su aplicación de mensajería nativa con el nombre de tu marca y el mensaje.

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

Reflexiones finales

¡Buen trabajo! Has implementado con éxito el envío de mensajes de texto RCS utilizando Go y la API Messages API de Vonage. ¡Pero RCS ofrece mucho más! Puedes intentar enviar respuestas sugeridas, imágenes de alta resolución y videos, o Rich Cards específicas de RCS.

El Messages API también proporciona estados de mensajes, que nos ayudan a entender lo que está pasando con nuestros mensajes RCS. En una futura entrada del blog, voy a mostrar cómo realizar un seguimiento de los estados de mensajes con webhooks.

Si tienes alguna pregunta o sugerencia sobre más contenido Go o RCS, únete a la conversación con nosotros en la Slack de la comunidad de Vonage o comunícate en X, antes conocido como Twitter. Nos encantaría saber qué es lo próximo que construirás.