BroadNet
Guia do desenvolvedor · API REST·OpenAPI 3.1

A API BroadNet.

Uma API REST para SMS, WhatsApp, RCS, Telegram, e-mail, Messenger, Instagram e notificações push. Cada requisição é enviada via HTTPS e autenticada com um token Bearer. Cada canal possui o seu próprio conjunto de caminhos, e toda a API é descrita numa especificação OpenAPI 3.1 disponível para download. Esta página aborda as chamadas iniciais da maioria das integrações, começando com um único SMS.

12 minutos de leitura·Atualizado em setembro de 2026Centro de desenvolvedores

Visão geral

A API BroadNet é uma API REST sobre HTTPS. Você se autentica com um token Bearer, envia uma solicitação JSON ou multipart para um endpoint de canal e recebe um ID de mensagem ou um resumo do lote. O status de entrega é enviado para a URL do webhook configurada na sua conta. A API completa, com 329 caminhos e 376 operações em oito canais, está publicada como uma especificação OpenAPI 3.1. Os exemplos nesta página usam curl, Node.js, Python, Java, C#, Go, Ruby e o SDK oficial TypeScript.

Ambientes

Os exemplos nesta página chamam a URL base de produção. As credenciais de teste, e para onde enviar o tráfego de teste, vêm com o seu acesso de teste: solicite-o em /signup e respondemos em até um dia útil.

AmbienteURL base
Produçãohttps://api.broadnet.me

Autenticação

Cada requisição inclui o seu token de acesso num cabeçalho HTTP. O token é emitido por conta e provém da sua conta BroadNet. Os exemplos nesta página o leem de uma variável de ambiente chamada BROADNET_TOKEN.

HTTP
Authorization: Bearer $BROADNET_TOKEN

Se o token estiver ausente ou for inválido, a API responde com HTTP 401 e um corpo de erro JSON no formato de erro padrão descrito abaixo. Não há nenhuma chamada que troque um nome de utilizador e palavra-passe por um token.

Enviar SMS

Envie um SMS com corpo JSON. Os quatro campos obrigatórios são o remetente, o destinatário, o texto e a codificação.

POSThttps://api.broadnet.me/sms/sendSms

Campos obrigatórios

CampoTipo de dadosDescrição
senderIdstringO seu ID de remetente aprovado, exibido ao destinatário como remetente.
destinationNumberstringNúmero do destinatário com código do país, apenas dígitos, sem sinal de mais.
messagestringO texto da mensagem.
messageTypestringCodificação: TEXT para texto GSM-7, UNICODE para árabe, emojis e outras escritas.

Campos opcionais

CampoTipo de dadosDescrição
charCountintegerContagem de caracteres, conforme devolvido por /sms/identify.
smsPartsintegerNúmero de segmentos, conforme devolvido por /sms/identify.
charLimitintegerCaracteres por segmento, conforme devolvido por /sms/identify.
expiryHourintegerPeríodo de validade em horas.
isSchedulebooleanDefina como verdadeiro para agendar a mensagem em vez de enviá-la agora.
delaynumberAguarde um pouco antes de enviar.
gmtstringO deslocamento GMT é usado para o agendamento.
time—Horário de envio agendado (com isSchedule).
repeat—Repetir configuração para envios agendados.
peIdstringIdentificação da entidade principal, quando exigida por um órgão regulador.
templateIdstringID de modelo registado, quando exigido por um órgão regulador.
telemarketerIdstringIdentificação de operador de telemarketing, quando exigida por órgão regulador.
campaignNamestringO seu rótulo para relatórios.
curl
curl -X POST https://api.broadnet.me/sms/sendSms \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "BroadNet",
    "destinationNumber": "447700900123",
    "message": "Your verification code is 482913",
    "messageType": "TEXT"
  }'

# 200 OK → response body is the message ID, e.g. 2603121407537573731
Node.js 18+ · fetch
// Node.js 18+ (fetch)
const res = await fetch("https://api.broadnet.me/sms/sendSms", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BROADNET_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    senderId: "BroadNet",
    destinationNumber: "447700900123",
    message: "Your verification code is 482913",
    messageType: "TEXT",
  }),
});

console.log(await res.text()); // message ID
Python · requests
import os, requests

r = requests.post(
    "https://api.broadnet.me/sms/sendSms",
    headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
    json={
        "senderId": "BroadNet",
        "destinationNumber": "447700900123",
        "message": "Your verification code is 482913",
        "messageType": "TEXT",
    },
)

print(r.status_code, r.text)  # message ID
Java 11+ · java.net.http
// Java 11+ — java.net.http is built in, nothing to install
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class SendSms {
    public static void main(String[] args) throws Exception {
        String json = "{"
            + "\"senderId\": \"BroadNet\", "
            + "\"destinationNumber\": \"447700900123\", "
            + "\"message\": \"Your verification code is 482913\", "
            + "\"messageType\": \"TEXT\""
            + "}";

        HttpRequest req = HttpRequest.newBuilder(URI.create("https://api.broadnet.me/sms/sendSms"))
            .header("Authorization", "Bearer " + System.getenv("BROADNET_TOKEN"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> res = HttpClient.newHttpClient()
            .send(req, HttpResponse.BodyHandlers.ofString());

        System.out.println(res.statusCode() + " " + res.body()); // 200 + message ID
    }
}
C# · .NET 6+ HttpClient
// .NET 6+ console app (Program.cs) — HttpClient is built in, no NuGet package
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("BROADNET_TOKEN"));

// PostAsJsonAsync sends Content-Type: application/json
var res = await http.PostAsJsonAsync("https://api.broadnet.me/sms/sendSms", new
{
    senderId = "BroadNet",
    destinationNumber = "447700900123",
    message = "Your verification code is 482913",
    messageType = "TEXT",
});

var id = await res.Content.ReadAsStringAsync();
Console.WriteLine($"{(int)res.StatusCode} {id}"); // 200 + message ID
Go · net/http
package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
		"senderId": "BroadNet",
		"destinationNumber": "447700900123",
		"message": "Your verification code is 482913",
		"messageType": "TEXT"
	}`)

	req, err := http.NewRequest(http.MethodPost, "https://api.broadnet.me/sms/sendSms", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("BROADNET_TOKEN"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	id, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(id)) // 200 + message ID
}
Ruby · Net::HTTP
require "net/http"
require "json"

uri = URI("https://api.broadnet.me/sms/sendSms")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch('BROADNET_TOKEN')}"
req["Content-Type"]  = "application/json"
req.body = {
  senderId:          "BroadNet",
  destinationNumber: "447700900123",
  message:           "Your verification code is 482913",
  messageType:       "TEXT"
}.to_json

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts "#{res.code} #{res.body}" # 200 + message ID
TypeScript SDK · @broadnet/cpaas-sdk
// npm install @broadnet/cpaas-sdk axios
import { Configuration, SMSSMSApi } from "@broadnet/cpaas-sdk";

const sms = new SMSSMSApi(
  new Configuration({
    basePath: "https://api.broadnet.me",
    accessToken: process.env.BROADNET_TOKEN!,
  }),
);

const res = await sms.smsSendsmsPost({
  sMSSmsRequest: {
    senderId: "BroadNet",
    destinationNumber: "447700900123",
    message: "Your verification code is 482913",
    messageType: "TEXT",
  },
});

console.log(res.data); // message ID

Uma chamada bem-sucedida devolve HTTP 200 e o ID da mensagem como corpo da resposta, sem envelope JSON :

200 OK
HTTP/1.1 200 OK

2603121407537573731

Codificação e segmentos

O campo messageType define a codificação, e a codificação define quantos caracteres cabem num segmento de SMS. Mensagens mais longas são divididas em segmentos e remontadas no aparelho.

messageTypeSMS únicoPor segmento (mensagem longa)Usar para
TEXT160153Apenas caracteres GSM-7.
UNICODE7067Qualquer outro alfabeto: árabe, cirílico, emojis, caracteres acentuados fora do padrão GSM-7.

Não tem certeza de qual codificação usar? Consulte a API. O endpoint `identify` analisa uma mensagem e devolve a sua codificação, contagem de caracteres, número de segmentos e caracteres por segmento, que você pode passar diretamente para a solicitação de envio.

curl · /sms/identify
curl -X POST https://api.broadnet.me/sms/identify \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Your verification code is 482913" }'
200 OK
{
  "message": "Your verification code is 482913",
  "messageType": "TEXT",
  "smscount": 1,
  "charCount": 32,
  "charLimit": 160
}

Experimente sem escrever código no Contador de caracteres SMS.

Formatos de números de telefone

Os números de destino são o código do país seguido do número nacional, apenas em dígitos. Não adicione um sinal de mais no início, o prefixo 00, espaços, hífens ou parênteses.

ExemploResultadoPorquê
447700900123VálidoCódigo do país 44 mais o número nacional, apenas dígitos.
+44 7700 900123RejeitarContém um sinal de mais e espaços. Remova-os primeiro.
07700900123RejeitarFormato nacional com zero à esquerda e sem código de país.

SMS em massa

Para enviar uma mensagem para vários destinatários, carregue um ficheiro de números numa solicitação de formulário multipart. A solicitação tem duas partes. A primeira, destinationNumberFile, é um ficheiro CSV ou TXT com os números. A segunda, bulkRequest, é uma string JSON com o remetente, o texto, a codificação e o nome da campanha.

POSThttps://api.broadnet.me/sms/sendbulk
curl · /sms/sendbulk
curl -X POST https://api.broadnet.me/sms/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F destinationNumberFile=@recipients.csv \
  -F 'bulkRequest={"senderId":"BroadNet","message":"Your statement is ready","messageType":"TEXT","campaignName":"statements"}'
200 OK
{
  "status": "success",
  "bulkSessionId": "1_20260228105000887",
  "credits": "9966465.42850",
  "deductcredits": "0.60000",
  "bulkListInfo": {
    "total": 4,
    "validCount": 3,
    "invalidCount": 0,
    "duplicate": 1
  }
}

O objeto bulkListInfo informa quantos números foram aceitos, quantos foram inválidos e quantos eram duplicados. Depois que um trabalho estiver em execução, você poderá geri-lo pelo seu ID de lote:

Método HTTPCaminho do ponto finalDescrição
GET/sms/listListe os seus trabalhos em lote com as contagens de trabalhos processados e pendentes.
GET/sms/pause?batch_Id=…Pausar uma tarefa em execução.
GET/sms/resume?batch_Id=…Retomar um trabalho pausado.
DELETE/sms/abort?batch_Id=…Cancelar uma tarefa; as mensagens pendentes não serão enviadas.
POST/sms/resendReenviar mensagens de uma tarefa anterior.
POST/sms/send-nowLibere a tarefa agendada imediatamente.
POST/sms/auto-scheduleAgende uma tarefa em lote automaticamente.
curl · batch control
# List your bulk jobs (each entry's id is the batch_Id below)
curl https://api.broadnet.me/sms/list \
  -H "Authorization: Bearer $BROADNET_TOKEN"

# Pause, then resume, a running job
curl "https://api.broadnet.me/sms/pause?batch_Id=1024" \
  -H "Authorization: Bearer $BROADNET_TOKEN"
curl "https://api.broadnet.me/sms/resume?batch_Id=1024" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

Pesquisa de número

Verifique o status de um número (HLR e MNP) antes de enviá-lo, por exemplo, para limpar uma lista ou para lidar com números portados. Passe o número como parâmetro de consulta `destinationNumber`. O parâmetro opcional `reqType` seleciona o tipo de pesquisa.

POSThttps://api.broadnet.me/sms/lookup
curl · /sms/lookup
curl -X POST "https://api.broadnet.me/sms/lookup?destinationNumber=447700900123" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

Status da entrega

O status de entrega é enviado para o URL do webhook configurado na sua conta BroadNet à medida que cada mensagem avança no seu ciclo de vida. Os status das mensagens seguem este ciclo de vida:

  • SUBMITTED · Aceito pela BroadNet e enfileirado na rede.
  • SENT · Entregue ao operador ou canal.
  • DELIVERED · Confirmado no aparelho.
  • READ · Aberto pelo destinatário, em canais que relatam leituras, como WhatsApp.
  • FAILED / REJECTED · Não entregue.

Você também pode consultar o status. Para WhatsApp, o endpoint bulk-insights devolve o status de cada destinatário num lote. Para trabalhos em massa de SMS, o endpoint list devolve a contagem de mensagens processadas e pendentes.

Erros

Um token Bearer ausente ou inválido é rejeitado no gateway API antes que a solicitação chegue à API. O gateway devolve HTTP 401 com um corpo JSON contendo dois campos: error e message.

401 Unauthorized
{
  "error": "Unauthorized",
  "message": "Missing Authorization token"
}

Erros gerados pela própria API, como um erro de validação 400, devolvem um corpo JSON chamado ExceptionResponse, com cinco campos: status, error, message, errorCode e requestUri. Os valores abaixo são apenas exemplos.

400 · ExceptionResponse
{
  "status": 400,
  "error": "Bad Request",
  "message": "…",
  "errorCode": "…",
  "requestUri": "/sms/sendSms"
}
StatusSignificado
200Sucesso.
400Solicitação inválida: erro de validação ou campo obrigatório ausente.
401Token Bearer ausente ou inválido.
403O token é válido, mas não permite a execução desta operação.
500Erro inesperado do servidor. Tente novamente mais tarde, aguardando um período de espera.

Tente novamente apenas em caso de erros de rede e respostas 5xx, com recuo exponencial. Corrija os erros 4xx em vez de tentar novamente. Se a sua conta também estiver vinculada via SMPP, os envios por lá devolverão códigos de status SMPP padrão, listados em Guia do Protocolo SMPP.

Outros canais de mensagens

O mesmo token e URL base funcionam para todos os canais. Esses são os endpoints de envio; a especificação OpenAPI documenta os seus campos e os endpoints de gestão associados (modelos, contactos, relatórios).

Canal de mensagensMétodo HTTPCaminho do ponto finalDescrição
SMSPOST/sms/sendSmsMensagem única (JSON).
SMSPOST/sms/sendbulkExtrair dados em lote de um ficheiro (multipart).
WhatsAppPOST/whatsapp/message/sendbulkTexto, conteúdo multimédia, modelos, interativo (multipart).
RCSPOST/rcs/message/sendbulkMensagens RCS (multipart).
TelegramPOST/telegram-sms/sendMensagens do Telegram.
EmailPOST/email/email-service/sendE-mail com assunto, corpo do e-mail e destinatários.
MessengerPOST/messenger/message/sendbulkMensagens do Facebook Messenger (multipart).
InstagramPOST/instagram/message/sendbulkMensagens do Instagram (multipartes).
PushPOST/push/message/sendNotificações push (JSON).

Um modelo de mensagem para WhatsApp, por exemplo:

curl · /whatsapp/message/sendbulk
curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F campaignName=order-updates \
  -F destinationNo=447700900123 \
  -F messageType=TEMPLATE \
  -F templateName=order_update \
  -F templateLanguage=en_US \
  -F bodyTemplateVariables=INV-400

Defina batchId como 0 para iniciar um novo lote. O campo destinationNo aceita vários números separados por vírgulas. A resposta contém o ID do lote que você usa para ler o status de cada destinatário.

SDK TypeScript

BroadNet publica um SDK oficial para TypeScript e Node.js : @broadnet/cpaas-sdk no npm. É gerado a partir da especificação OpenAPI BroadNet, inclui módulos CommonJS e ES com definições de tipo completas e possui uma classe API por recurso de canal. A sua única dependência de execução é o axios, que o npm instala junto.

terminal
npm install @broadnet/cpaas-sdk axios
TypeScript · WhatsApp
import { Configuration, WhatsAppWhatsAppMessagingAPIApi } from "@broadnet/cpaas-sdk";

const wa = new WhatsAppWhatsAppMessagingAPIApi(
  new Configuration({
    basePath: "https://api.broadnet.me",
    accessToken: process.env.BROADNET_TOKEN!,
  }),
);

const res = await wa.whatsappMessageSendbulkPost({
  campaignName: "order-updates",
  messageType: "TEXT",
  destinationNo: "447700900123",
  content: "Your order has shipped.",
});

console.log(res.data); // batchId + per-file acceptance counts

Para qualquer outra linguagem, chame a API REST diretamente (os exemplos Node.js, Python, Java, C#, Go e Ruby acima não usam a biblioteca BroadNet) ou gere um cliente a partir da especificação OpenAPI.

Especificação OpenAPI

A API completa está descrita num ficheiro OpenAPI 3.1: 329 caminhos e 376 operações em oito canais. Esta é uma cópia pública da especificação com os exemplos internos removidos. Importe-a para o Postman ou Insomnia, navegue por ela na interface do Swagger ou gere um cliente.

terminal
curl -O https://www.broadnet.me/developers/openapi.yaml

# Generate a client in any language, e.g. Python
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml -g python -o broadnet-python

Prefere o Postman? Importe a especificação para obter todas as operações ou comece com uma pequena coleção de chamadas essenciais.

API HTTP legada (/websmpp)

Contas iniciadas na plataforma BroadNet da era SMPP podem usar a API HTTP legada no caminho /websmpp. Ela permanece em funcionamento para essas integrações existentes e está documentada na especificação OpenAPI. A API HTTP legada aceita credenciais como parâmetros de requisição (utilizador e palavra-passe, ou chave de acesso) em vez de um token Bearer. Novas integrações devem usar a API REST descrita acima.

Método HTTPCaminho do ponto finalDescrição
GET/websmpp/websmsEnviar um SMS. Adicione um horário e o fuso horário (GMT) para agendá-lo.user, pass (or accesskey), sid, mno, type, text, schtime, gmt
POST/websmpp/json/smsEnvie com um objeto de campanha JSON que contenha as credenciais, o remetente, os números e o texto.campaign { username, password, sender, gsm, text, type }
GET/websmpp/websmsstatusStatus de uma mensagem enviada, pelo seu ID de resposta.respid, format
POST/websmpp/api/dlrreportRelatório de entregas para um determinado período, em formato de folha de cálculo.username, pass, from_date, to_date
GET/websmpp/hlr/lookupPesquisa HLR para um número.username, password, destination
curl · legacy
# Legacy HTTP API — credentials as query parameters (existing integrations only)
curl "https://api.broadnet.me/websmpp/websms?user=USERNAME&pass=PASSWORD&sid=BroadNet&mno=447700900123&type=1&text=Hello"

# Status of a submitted message
curl "https://api.broadnet.me/websmpp/websmsstatus?respid=MESSAGE_ID&format=json"

Perguntas frequentes

Como faço para autenticar?

Envie o seu token de acesso no cabeçalho Authorization: Bearer em todas as requisições. O token é proveniente da sua conta BroadNet ; não há nenhuma chamada de geração de token na API. Um token ausente ou inválido é rejeitado no gateway API com HTTP 401 e um corpo JSON contendo dois campos: error e message. Mantenha o token numa variável de ambiente ou num gestor de segredos, nunca no controlo de versão ou no código do lado do cliente.

Qual é a URL base?

Cada exemplo chama a produção, https://api.broadnet.me. As credenciais de teste, e para onde enviar o tráfego de teste, vêm com o seu acesso de teste: solicite-o em /signup e respondemos em até um dia útil.

Como faço para enviar texto em árabe ou outro idioma Unicode?

Defina messageType como UNICODE. Use TEXT somente quando todos os caracteres estiverem no alfabeto GSM-7. Se não tiver certeza, chame POST /sms/identify com a mensagem: ela devolve o messageType, a contagem de caracteres, o número de segmentos e os caracteres por segmento.

O que é devolvido após um envio bem-sucedido?

POST /sms/sendSms devolve HTTP 200 e o ID da mensagem como corpo da resposta. Os envios em massa devolvem um objeto JSON com status, bulkSessionId, credits, deductcredits e bulkListInfo.

Como faço para enviar um SMS para vários destinatários?

Use POST /sms/sendbulk com um upload multipart: destinationNumberFile é um ficheiro CSV ou TXT contendo números e bulkRequest é uma string JSON com senderId, message, messageType e campaignName. Os trabalhos podem então ser listados, pausados, retomados ou cancelados por ID do lote.

Como faço para obter o status da entrega?

O status de entrega é enviado para o URL do webhook configurado na sua conta. Para WhatsApp, o status de cada destinatário também pode ser lido em /whatsapp/message/bulk-insights.

Existe um SDK ?

Sim, uma opção: o SDK oficial TypeScript / Node.js, @broadnet/cpaas-sdk no npm, gerado a partir da especificação OpenAPI BroadNet. Para qualquer outra linguagem, chame a API REST diretamente ou gere um cliente a partir da especificação OpenAPI 3.1 em /developers/openapi.yaml.

O que é a API /websmpp?

A API HTTP legada, mantida para integrações existentes da era SMPP, aceita credenciais como parâmetros de requisição. Novas integrações devem usar a API REST de token Bearer, documentada nesta página.

Comece a enviar

Pronto para enviar o seu primeiro SMS?