Premiers pas

Démarrage rapide

Envoyez votre premier SMS avec Pulsr en TypeScript ou en Python. Il vous faut un compte, une clé API et un téléphone sur lequel lire les messages.

1. Récupérez vos identifiants

Dans le tableau de bord Pulsr, ouvrez Clés API et créez une clé. La même page affiche votre URL de base, l’adresse à laquelle partent toutes les requêtes. Enregistrez les deux en variables d’environnement :

Terminal

export PULSR_API_URL="https://<your-base-url>"export PULSR_API_KEY="<your-api-key>"

2. Ajoutez l’utilitaire client

L’API, c’est simplement du HTTPS et du JSON : un petit utilitaire suffit. Il ajoute l’en-tête Authorization, encode le corps et transforme les réponses d’erreur en exceptions. Le reste de la documentation s’en sert.

Terminal

# TypeScript: nothing to install, fetch is built into Node.js 18+# Pythonpip install requests

client.ts

const BASE_URL = process.env.PULSR_API_URL!;const API_KEY = process.env.PULSR_API_KEY!;export class PulsrError extends Error {  constructor(public status: number, public body: any) {    // SMS and RCS errors carry a description, voice and verify a requestError    const legacy = body?.requestError?.serviceException?.text;    super(body?.description ?? legacy ?? `HTTP ${status}`);  }}export async function pulsr<T = any>(  method: string,  path: string,  body?: unknown,): Promise<T> {  const res = await fetch(`${BASE_URL}${path}`, {    method,    headers: {      "Authorization": `App ${API_KEY}`,      "Content-Type": "application/json",      "Accept": "application/json",    },    body: body === undefined ? undefined : JSON.stringify(body),  });  const data = await res.json().catch(() => null);  if (!res.ok) throw new PulsrError(res.status, data);  return data as T;}

3. Envoyez un message

Remplacez la destination par votre propre numéro de mobile, au format international sans le +.

send.ts

import { pulsr } from "./client";const res = await pulsr("POST", "/sms/3/messages", {  messages: [    {      sender: "Pulsr",      destinations: [{ to: "33639981234" }],      content: { text: "Hello from Pulsr! It works." },    },  ],});const { messageId, status } = res.messages[0];console.log(messageId, status.name); // ... PENDING_ACCEPTED

L’API répond dès que le message est accepté. Conservez le messageId : c’est lui qui vous permettra de retrouver le rapport de remise.

Réponse · 200 OK

{  "bulkId": "2034072219640523072",  "messages": [    {      "messageId": "2250be2d4219-3af1-78856-aabe-1362af1edfd2",      "status": {        "groupId": 1,        "groupName": "PENDING",        "id": 26,        "name": "PENDING_ACCEPTED",        "description": "Message sent to next instance"      },      "destination": "33639981234",      "details": { "messageCount": 1 }    }  ]}

4. Vérifiez qu’il est arrivé

Votre téléphone devrait vibrer en quelques secondes. Pour suivre la remise depuis votre code, récupérez le rapport de remise du message. En production, faites plutôt pousser les rapports vers un webhook au lieu d’interroger l’API.

report.ts

const { results } = await pulsr("GET", `/sms/3/reports?messageId=${messageId}`);if (results.length === 0) {  console.log("No report yet, try again in a few seconds");} else {  console.log(results[0].status.groupName); // DELIVERED}

Un status.groupName égal à DELIVERED signifie que le téléphone a reçu le message. Les autres valeurs sont expliquées dans Erreurs et statuts.

Et ensuite

1. Récupérez vos identifiants

Terminal

export PULSR_API_URL="https://<your-base-url>"export PULSR_API_KEY="<your-api-key>"

2. Ajoutez l’utilitaire client

Terminal

# TypeScript: nothing to install, fetch is built into Node.js 18+# Pythonpip install requests

client.ts

const BASE_URL = process.env.PULSR_API_URL!;const API_KEY = process.env.PULSR_API_KEY!;export class PulsrError extends Error {  constructor(public status: number, public body: any) {    // SMS and RCS errors carry a description, voice and verify a requestError    const legacy = body?.requestError?.serviceException?.text;    super(body?.description ?? legacy ?? `HTTP ${status}`);  }}export async function pulsr<T = any>(  method: string,  path: string,  body?: unknown,): Promise<T> {  const res = await fetch(`${BASE_URL}${path}`, {    method,    headers: {      "Authorization": `App ${API_KEY}`,      "Content-Type": "application/json",      "Accept": "application/json",    },    body: body === undefined ? undefined : JSON.stringify(body),  });  const data = await res.json().catch(() => null);  if (!res.ok) throw new PulsrError(res.status, data);  return data as T;}

3. Envoyez un message

Remplacez la destination par votre propre numéro de mobile, au format international sans le +.

send.ts

import { pulsr } from "./client";const res = await pulsr("POST", "/sms/3/messages", {  messages: [    {      sender: "Pulsr",      destinations: [{ to: "33639981234" }],      content: { text: "Hello from Pulsr! It works." },    },  ],});const { messageId, status } = res.messages[0];console.log(messageId, status.name); // ... PENDING_ACCEPTED

L’API répond dès que le message est accepté. Conservez le messageId : c’est lui qui vous permettra de retrouver le rapport de remise.

Réponse · 200 OK

{  "bulkId": "2034072219640523072",  "messages": [    {      "messageId": "2250be2d4219-3af1-78856-aabe-1362af1edfd2",      "status": {        "groupId": 1,        "groupName": "PENDING",        "id": 26,        "name": "PENDING_ACCEPTED",        "description": "Message sent to next instance"      },      "destination": "33639981234",      "details": { "messageCount": 1 }    }  ]}

4. Vérifiez qu’il est arrivé

report.ts

const { results } = await pulsr("GET", `/sms/3/reports?messageId=${messageId}`);if (results.length === 0) {  console.log("No report yet, try again in a few seconds");} else {  console.log(results[0].status.groupName); // DELIVERED}

Un status.groupName égal à DELIVERED signifie que le téléphone a reçu le message. Les autres valeurs sont expliquées dans Erreurs et statuts.