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.
| Ambiente | URL base |
|---|---|
| Produção | https://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.
Authorization: Bearer $BROADNET_TOKENSe 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.
Campos obrigatórios
| Campo | Tipo de dados | Descrição |
|---|---|---|
| senderId | string | O seu ID de remetente aprovado, exibido ao destinatário como remetente. |
| destinationNumber | string | Número do destinatário com código do país, apenas dígitos, sem sinal de mais. |
| message | string | O texto da mensagem. |
| messageType | string | Codificação: TEXT para texto GSM-7, UNICODE para árabe, emojis e outras escritas. |
Campos opcionais
| Campo | Tipo de dados | Descrição |
|---|---|---|
| charCount | integer | Contagem de caracteres, conforme devolvido por /sms/identify. |
| smsParts | integer | Número de segmentos, conforme devolvido por /sms/identify. |
| charLimit | integer | Caracteres por segmento, conforme devolvido por /sms/identify. |
| expiryHour | integer | Período de validade em horas. |
| isSchedule | boolean | Defina como verdadeiro para agendar a mensagem em vez de enviá-la agora. |
| delay | number | Aguarde um pouco antes de enviar. |
| gmt | string | O deslocamento GMT é usado para o agendamento. |
| time | — | Horário de envio agendado (com isSchedule). |
| repeat | — | Repetir configuração para envios agendados. |
| peId | string | Identificação da entidade principal, quando exigida por um órgão regulador. |
| templateId | string | ID de modelo registado, quando exigido por um órgão regulador. |
| telemarketerId | string | Identificação de operador de telemarketing, quando exigida por órgão regulador. |
| campaignName | string | O seu rótulo para relatórios. |
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)
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 IDimport 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 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
}
}// .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 IDpackage 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
}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// 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 IDUma chamada bem-sucedida devolve HTTP 200 e o ID da mensagem como corpo da resposta, sem envelope JSON :
HTTP/1.1 200 OK
2603121407537573731Codificaçã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.
| messageType | SMS único | Por segmento (mensagem longa) | Usar para |
|---|---|---|---|
| TEXT | 160 | 153 | Apenas caracteres GSM-7. |
| UNICODE | 70 | 67 | Qualquer 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 -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" }'{
"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.
| Exemplo | Resultado | Porquê |
|---|---|---|
| 447700900123 | Válido | Código do país 44 mais o número nacional, apenas dígitos. |
| +44 7700 900123 | Rejeitar | Contém um sinal de mais e espaços. Remova-os primeiro. |
| 07700900123 | Rejeitar | Formato 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.
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"}'{
"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 HTTP | Caminho do ponto final | Descrição |
|---|---|---|
| GET | /sms/list | Liste 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/resend | Reenviar mensagens de uma tarefa anterior. |
| POST | /sms/send-now | Libere a tarefa agendada imediatamente. |
| POST | /sms/auto-schedule | Agende uma tarefa em lote automaticamente. |
# 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.
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.
{
"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.
{
"status": 400,
"error": "Bad Request",
"message": "…",
"errorCode": "…",
"requestUri": "/sms/sendSms"
}| Status | Significado |
|---|---|
| 200 | Sucesso. |
| 400 | Solicitação inválida: erro de validação ou campo obrigatório ausente. |
| 401 | Token Bearer ausente ou inválido. |
| 403 | O token é válido, mas não permite a execução desta operação. |
| 500 | Erro 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 mensagens | Método HTTP | Caminho do ponto final | Descrição |
|---|---|---|---|
| SMS | POST | /sms/sendSms | Mensagem única (JSON). |
| SMS | POST | /sms/sendbulk | Extrair dados em lote de um ficheiro (multipart). |
| POST | /whatsapp/message/sendbulk | Texto, conteúdo multimédia, modelos, interativo (multipart). | |
| RCS | POST | /rcs/message/sendbulk | Mensagens RCS (multipart). |
| Telegram | POST | /telegram-sms/send | Mensagens do Telegram. |
| POST | /email/email-service/send | E-mail com assunto, corpo do e-mail e destinatários. | |
| Messenger | POST | /messenger/message/sendbulk | Mensagens do Facebook Messenger (multipart). |
| POST | /instagram/message/sendbulk | Mensagens do Instagram (multipartes). | |
| Push | POST | /push/message/send | Notificações push (JSON). |
Um modelo de mensagem para WhatsApp, por exemplo:
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-400Defina 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.
npm install @broadnet/cpaas-sdk axiosimport { 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 countsPara 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.
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-pythonPrefere 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 HTTP | Caminho do ponto final | Descrição |
|---|---|---|
| GET | /websmpp/websms | Enviar 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/sms | Envie 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/websmsstatus | Status de uma mensagem enviada, pelo seu ID de resposta.respid, format |
| POST | /websmpp/api/dlrreport | Relatório de entregas para um determinado período, em formato de folha de cálculo.username, pass, from_date, to_date |
| GET | /websmpp/hlr/lookup | Pesquisa HLR para um número.username, password, destination |
# 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.