API WhatsApp Business

L'integrazione WhatsApp tramite Qlara ti consente di inviare messaggi ai clienti su larga scala con consegna affidabile e supporto di rich media. Sfrutta l'enorme base di utenti di WhatsApp per raggiungere il tuo pubblico con template, notifiche e comunicazioni personalizzate.

Panoramica

L'integrazione WhatsApp tramite Qlara fornisce due modalità di invio distinte:

• Messaggistica basata su template: Invia template pre-approvati in qualsiasi momento senza restrizioni di tempo
• Messaggistica libera: Invia messaggi personalizzati entro una finestra di 24 ore dopo l'interazione del cliente

L'API supporta rich media inclusi testo, immagini, video, file audio, documenti, sticker, posizioni e reazioni emoji. Con catene di fallback configurabili (WhatsApp → RCS → SMS), puoi assicurare che i tuoi messaggi raggiungano i clienti anche se WhatsApp non è disponibile.

Autenticazione

Tutte le richieste API WhatsApp richiedono autenticazione utilizzando la tua API key. Includi la API key nell'header X-Api-Key:

X-Api-Key: your_api_key_here

Invio di Messaggi

Endpoint di Invio

POST https://lora-api.agiletelecom.com/api/message-server/whatsapp/send

Parametri della Richiesta

Parametro	Tipo	Richiesto	Descrizione
destination	string	Sì	Numero di telefono del destinatario in formato internazionale (es. +39XXXXXXXXXX)
phoneNumberId	string	Sì	L'ID del tuo numero di telefono WhatsApp Business
template	object	Condizionale	Oggetto template per messaggi approvati (richiesto se body non è fornito)
body	string	Condizionale	Testo del messaggio libero (richiesto se template non è fornito; valido solo entro 24h dall'interazione del cliente)
media	object	No	Contenuto media (immagine, video, audio, documento, sticker, posizione)
fallbackRcs	boolean	No	Abilita fallback RCS (default: false)
fallbackSms	boolean	No	Abilita fallback SMS (default: false)

Oggetto Template

\{
  "name": "template_name",
  "language": "en",
  "parameters": [
    "value1",
    "value2"
  ]
\}

Tipi di Media

WhatsApp supporta i seguenti tipi di media nei tuoi messaggi:

• text: Messaggi di testo semplice
• image: Immagini JPEG e PNG
• video: File video MP4 e 3GPP
• audio: File audio MP3, OGG e WAV
• document: Documenti PDF e Office
• sticker: Sticker animati e statici WebP
• location: Coordinate con etichetta opzionale
• emoji reactions: Reagisci ai messaggi con emoji

Catena di Fallback

Configura la messaggistica di fallback per assicurare la consegna quando WhatsApp non è disponibile:

\{
  "destination": "+39XXXXXXXXXX",
  "phoneNumberId": "your_phone_id",
  "body": "Your message",
  "fallbackRcs": true,
  "fallbackSms": true
\}

Se la consegna WhatsApp fallisce:

1. Il messaggio tenta la consegna via RCS (se fallbackRcs è abilitato)
2. Se RCS non è disponibile, fallback a SMS (se fallbackSms è abilitato)

Gestione Numeri di Telefono

Endpoint Get Phone Numbers

GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers

Recupera tutti i numeri di telefono WhatsApp Business registrati associati al tuo account.

Risposta

\{
  "phoneNumbers": [
    \{
      "id": "phone_number_id",
      "phoneNumber": "+39XXXXXXXXXX",
      "displayName": "Your Business Name",
      "status": "CONNECTED"
    \}
  ]
\}

Formato della Risposta

Le richieste di invio riuscite restituiscono:

\{
  "messageId": "wamid.XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "simulation": false,
  "results": [
    \{
      "destination": "+39XXXXXXXXXX",
      "accepted": true
    \}
  ]
\}

Campo	Tipo	Descrizione
messageId	string	Identificatore univoco per questo messaggio
simulation	boolean	Indica se si trattava di un invio di test/simulazione
results	array	Array dei risultati per destinatario
accepted	boolean	Se il destinatario ha accettato il messaggio

Template

Gestione Template

WhatsApp richiede che i template di messaggio siano approvati da Meta prima dell'invio. I template assicurano qualità e prevengono lo spam.

Processo di Approvazione Template

1. Invia il template per la revisione tramite l'API
2. Meta esamina i template entro 24 ore
3. Una volta approvato, usa il nome del template nelle richieste di invio
4. Puoi modificare i template approvati (richiede una nuova approvazione)

Operazioni CRUD

Usa i seguenti endpoint per la gestione dei template:

• Create: POST /api/message-server/whatsapp/templates
• List: GET /api/message-server/whatsapp/templates
• Get: GET /api/message-server/whatsapp/templates/{id}
• Update: PUT /api/message-server/whatsapp/templates/{id}
• Delete: DELETE /api/message-server/whatsapp/templates/{id}

Link Tracciati

Usa il placeholder shortLinkT1 nei tuoi messaggi per generare automaticamente link brevi tracciati:

Your message text with \{shortLinkT1\} placeholder

Questo abilita analitiche e tracciamento dei clic per le tue campagne.

Esempi di Codice

cURL

curl -X POST https://lora-api.agiletelecom.com/api/message-server/whatsapp/send \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '\{
    "destination": "+39XXXXXXXXXX",
    "phoneNumberId": "your_phone_id",
    "body": "Hello from Qlara!"
  \}'

Python

import requests

api_key = "your_api_key"
url = "https://lora-api.agiletelecom.com/api/message-server/whatsapp/send"

payload = \{
    "destination": "+39XXXXXXXXXX",
    "phoneNumberId": "your_phone_id",
    "body": "Hello from Qlara!"
\}

headers = \{
    "X-Api-Key": api_key,
    "Content-Type": "application/json"
\}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Node.js

const fetch = require('node-fetch');

const apiKey = 'your_api_key';
const url = 'https://lora-api.agiletelecom.com/api/message-server/whatsapp/send';

const payload = \{
  destination: '+39XXXXXXXXXX',
  phoneNumberId: 'your_phone_id',
  body: 'Hello from Qlara!'
\};

const options = \{
  method: 'POST',
  headers: \{
    'X-Api-Key': apiKey,
    'Content-Type': 'application/json'
  \},
  body: JSON.stringify(payload)
\};

fetch(url, options)
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));

PHP

<?php
$apiKey = 'your_api_key';
$url = 'https://lora-api.agiletelecom.com/api/message-server/whatsapp/send';

$payload = [
    'destination' => '+39XXXXXXXXXX',
    'phoneNumberId' => 'your_phone_id',
    'body' => 'Hello from Qlara!'
];

$options = [
    'http' => [
        'header' => "X-Api-Key: $apiKey\r\nContent-Type: application/json\r\n",
        'method' => 'POST',
        'content' => json_encode($payload)
    ]
];

$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
echo $response;
?>

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class WhatsAppExample \{
    public static void main(String[] args) throws Exception \{
        String apiKey = "your_api_key";
        String url = "https://lora-api.agiletelecom.com/api/message-server/whatsapp/send";
        
        String json = "\{\\"destination\\": \\"+39XXXXXXXXXX\\", \\"phoneNumberId\\": \\"your_phone_id\\", \\"body\\": \\"Hello from Qlara!\\"\}";
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("X-Api-Key", apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();
        
        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    \}
\}

C#

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program \{
    static async Task Main() \{
        var apiKey = "your_api_key";
        var url = "https://lora-api.agiletelecom.com/api/message-server/whatsapp/send";
        
        var payload = new \{
            destination = "+39XXXXXXXXXX",
            phoneNumberId = "your_phone_id",
            body = "Hello from Qlara!"
        \};
        
        var json = System.Text.Json.JsonSerializer.Serialize(payload);
        
        using (var client = new HttpClient()) \{
            client.DefaultRequestHeaders.Add("X-Api-Key", apiKey);
            
            var content = new StringContent(json, Encoding.UTF8, "application/json");
            var response = await client.PostAsync(url, content);
            var result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        \}
    \}
\}

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() \{
	apiKey := "your_api_key"
	url := "https://lora-api.agiletelecom.com/api/message-server/whatsapp/send"
	
	payload := map[string]string\{
		"destination":   "+39XXXXXXXXXX",
		"phoneNumberId": "your_phone_id",
		"body":          "Hello from Qlara!",
	\}
	
	jsonData, _ := json.Marshal(payload)
	
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	req.Header.Set("X-Api-Key", apiKey)
	req.Header.Set("Content-Type", "application/json")
	
	client := &http.Client\{\}
	resp, _ := client.Do(req)
	body, _ := ioutil.ReadAll(resp.Body)
	fmt.Println(string(body))
\}

Ruby

require 'net/http'
require 'json'
require 'uri'

api_key = 'your_api_key'
url = URI('https://lora-api.agiletelecom.com/api/message-server/whatsapp/send')

payload = \{
  destination: '+39XXXXXXXXXX',
  phoneNumberId: 'your_phone_id',
  body: 'Hello from Qlara!'
\}

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request['X-Api-Key'] = api_key
request['Content-Type'] = 'application/json'
request.body = payload.to_json

response = http.request(request)
puts response.body

Webhook e Consegna

Stato di Consegna

Monitora la consegna dei messaggi tramite webhook configurati nelle impostazioni del tuo account.

Codici di Stato

Codice	Stato	Descrizione
3	Consegnato	Messaggio consegnato con successo ai server WhatsApp
6	Non Consegnabile	Messaggio non potrebbe essere consegnato al destinatario

Payload Webhook

L'URL di callback riceve conferme di consegna con informazioni di stato dettagliate:

\{
  "messageId": "wamid.XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "destination": "+39XXXXXXXXXX",
  "status": 3,
  "timestamp": "2024-01-15T10:30:45Z"
\}

Best Practice

• Usa i template per messaggi sensibili al tempo e promozionali per assicurare approvazione consistente e invio in qualsiasi momento
• Sfrutta le catene di fallback per massimizzare i tassi di consegna su più canali
• Monitora i callback webhook per tracciare la consegna dei messaggi in tempo reale
• Testa i template durante lo sviluppo per assicurare una corretta sostituzione delle variabili
• Mantieni i numeri di telefono accurati e aggiornati nel tuo sistema
• Usa link tracciati per l'analitiche delle campagne e la misurazione delle prestazioni
• Rispetta la finestra di 24 ore per messaggi liberi dopo l'interazione del cliente