API Quickstart

Questa guida ti mostrerà come inviare il tuo primo messaggio utilizzando le API di UniMsg. In pochi minuti sarai operativo.

Prerequisiti

Un account UniMsg attivo (crea un account)
Le tue credenziali API (Client ID e Client Secret)
Crediti disponibili sul tuo account

Step 1: Ottenere un Access Token

UniMsg utilizza OAuth 2.0 con il flusso Client Credentials. Per prima cosa, ottieni un access token:

cURL

curl -X POST https://api.unimsg.app/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=demo_xxxxxxxxxxxx" \
  -d "client_secret=sk_test_xxxxxxxxxxxx"

PHP

<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.unimsg.app/oauth/token',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'grant_type' => 'client_credentials',
        'client_id' => 'demo_xxxxxxxxxxxx',
        'client_secret' => 'sk_test_xxxxxxxxxxxx'
    ])
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
$accessToken = $data['access_token'];
curl_close($ch);

Python

import requests

response = requests.post('https://api.unimsg.app/oauth/token', data={
    'grant_type': 'client_credentials',
    'client_id': 'demo_xxxxxxxxxxxx',
    'client_secret': 'sk_test_xxxxxxxxxxxx'
})

access_token = response.json()['access_token']

Node.js

const axios = require('axios');

const response = await axios.post('https://api.unimsg.app/oauth/token',
    new URLSearchParams({
        grant_type: 'client_credentials',
        client_id: 'demo_xxxxxxxxxxxx',
        client_secret: 'sk_test_xxxxxxxxxxxx'
    })
);

const accessToken = response.data.access_token;

Risposta:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600
}

Nota: L'access token ha una durata di 1 ora. Salvalo e riutilizzalo fino alla scadenza.

Step 2: Inviare un SMS

Con l'access token, puoi ora inviare messaggi. Ecco un esempio per SMS:

cURL

curl -X POST https://api.unimsg.app/v1/sms/send \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+39123456789",
    "message": "Ciao! Questo è un messaggio di test da UniMsg.",
    "sender": "UniMsg"
  }'

PHP

<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.unimsg.app/v1/sms/send',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $accessToken,
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to' => '+39123456789',
        'message' => 'Ciao! Questo è un messaggio di test da UniMsg.',
        'sender' => 'UniMsg'
    ])
]);
$response = curl_exec($ch);
$result = json_decode($response, true);
curl_close($ch);

if ($result['success']) {
    echo "Messaggio inviato! ID: " . $result['data']['message_id'];
}

Python

import requests

response = requests.post(
    'https://api.unimsg.app/v1/sms/send',
    headers={
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json'
    },
    json={
        'to': '+39123456789',
        'message': 'Ciao! Questo è un messaggio di test da UniMsg.',
        'sender': 'UniMsg'
    }
)

result = response.json()
if result['success']:
    print(f"Messaggio inviato! ID: {result['data']['message_id']}")

Node.js

const axios = require('axios');

const response = await axios.post('https://api.unimsg.app/v1/sms/send', {
    to: '+39123456789',
    message: 'Ciao! Questo è un messaggio di test da UniMsg.',
    sender: 'UniMsg'
}, {
    headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
    }
});

if (response.data.success) {
    console.log(`Messaggio inviato! ID: ${response.data.data.message_id}`);
}

Risposta di successo:

{
    "success": true,
    "data": {
        "message_id": "msg_xxxxxxxxxxxx",
        "status": "queued",
        "credits_used": 1,
        "created_at": "2024-01-15T10:30:00Z"
    }
}

Step 3: Verificare lo Stato

Puoi controllare lo stato di un messaggio usando il suo ID:

curl -X GET https://api.unimsg.app/v1/messages/msg_xxxxxxxxxxxx \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Risposta:

{
    "success": true,
    "data": {
        "message_id": "msg_xxxxxxxxxxxx",
        "channel": "sms",
        "to": "+39123456789",
        "status": "delivered",
        "status_history": [
            {"status": "queued", "timestamp": "2024-01-15T10:30:00Z"},
            {"status": "sent", "timestamp": "2024-01-15T10:30:01Z"},
            {"status": "delivered", "timestamp": "2024-01-15T10:30:03Z"}
        ],
        "credits_used": 1
    }
}

Gestione Errori

In caso di errore, l'API restituisce una risposta con success: false:

{
    "success": false,
    "error": {
        "code": "INSUFFICIENT_CREDITS",
        "message": "Crediti insufficienti per completare l'operazione"
    }
}

Codici Errore Comuni

Codice	Descrizione	Soluzione
`UNAUTHORIZED`	Token non valido o scaduto	Rigenera l'access token
`INSUFFICIENT_CREDITS`	Crediti non sufficienti	Ricarica il tuo account
`INVALID_PHONE`	Numero telefono non valido	Verifica il formato (+39...)
`RATE_LIMITED`	Troppi richieste	Riprova dopo qualche secondo

Prossimi Passi

Telegram FAQ