API Outbound

Quand utiliser ceci

1. Obtenez une clé API

Ouvrez clé API dans votre tableau de bord et cliquez sur Générer. Vous verrez la clé complète une seule fois — copiez-la maintenant et stockez-la quelque part de sûr (par ex. votre gestionnaire de secrets). Si vous la perdez, générez-en une nouvelle ; l'ancienne cesse de fonctionner immédiatement.

Les clés commencent par sk_live_ suivi de 64 caractères hexadécimaux. Traitez-la comme un mot de passe : ne la commitez jamais dans git, ne l'exposez jamais dans le code du navigateur.

2. Point de terminaison

POST https://api.socialhook.io/api/v1/outbound/<your_user_id>/send
Content-Type: application/json

Votre user_id est affiché dans l'URL de la page de clé API. Le chemin est limité à l'utilisateur intentionnellement afin qu'une clé divulguée ne puisse impacter qu'un seul compte.

3. Authentification

Choisissez la méthode qui convient à votre configuration. Les deux fonctionnent avec le même point de terminaison.

Méthode A — Clé simple (n8n, Make, Zapier, outils no-code)

Ajoutez un seul en-tête. Aucune signature requise.

X-Api-Key: <your_api_key>

# Method: POST
# URL:    https://api.socialhook.io/api/v1/outbound/<your_user_id>/send
# Header: X-Api-Key  →  sk_live_…
# Body (JSON):
{
  "platform": "whatsapp",
  "to": "447911123456",
  "message_text": "Hello from n8n!"
}

Méthode B — Requête signée (HMAC-SHA256, serveurs personnalisés)

Construisez la signature en hachant HMAC-SHA256 <timestamp>.<raw_body> avec votre clé API, puis envoyez le digest hexadécimal minuscule dans l'en-tête X-Socialhook-Signature préfixé par sha256=. Les requêtes avec des horodatages datant de plus de 5 minutes de l'heure du serveur sont rejetées.

X-Socialhook-Timestamp: <unix_seconds>
X-Socialhook-Signature: sha256=<hmac_hex>

const crypto = require('crypto');

const API_KEY = process.env.SOCIALHOOK_API_KEY;     // sk_live_…
const USER_ID = process.env.SOCIALHOOK_USER_ID;     // shown on the API key page

const body = JSON.stringify({
  platform: 'whatsapp',
  to: '447911123456',
  message_text: 'Hello from your SocialHook integration!',
});
const ts  = Math.floor(Date.now() / 1000).toString();
const sig = crypto
  .createHmac('sha256', API_KEY)
  .update(`${ts}.${body}`)
  .digest('hex');

const res = await fetch(
  `https://api.socialhook.io/api/v1/outbound/${USER_ID}/send`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Socialhook-Timestamp': ts,
      'X-Socialhook-Signature': `sha256=${sig}`,
    },
    body,
  }
);

if (!res.ok) throw new Error(await res.text());

# Drop your real API_KEY and USER_ID in here
TS=$(date +%s)
BODY='{"platform":"whatsapp","to":"447911123456","message_text":"Hello!"}'
SIG=$(printf "%s.%s" "$TS" "$BODY" | openssl dgst -sha256 -hmac "$API_KEY" | awk '{print $2}')

curl -X POST https://api.socialhook.io/api/v1/outbound/$USER_ID/send \
  -H "Content-Type: application/json" \
  -H "X-Socialhook-Timestamp: $TS" \
  -H "X-Socialhook-Signature: sha256=$SIG" \
  -d "$BODY"

4. Corps de la requête par plateforme

{
  "platform": "whatsapp",
  "to": "447911123456",
  "message_text": "Hello from your integration!"
}

{
  "platform": "facebook",
  "to": "<recipient_psid>",
  "page_id": "<your_facebook_page_id>",
  "message_text": "Hi from SocialHook"
}

{
  "platform": "instagram",
  "to": "<recipient_psid>",
  "page_id": "<your_facebook_page_id>",
  "message_text": "Hey from SocialHook"
}

5. Codes de réponse

Réponse automatique (éviter le point de terminaison)

Si votre seul besoin sortant est de répondre aux messages entrants, vous n'avez pas du tout besoin d'appeler ce point de terminaison. Quand SocialHook vous livre un webhook, votre serveur peut répondre avec l'un de :

// Single reply
{ "reply": "Thanks — got your message!" }

// Or multiple in order
{ "replies": ["Thanks!", "We'll get back to you within an hour."] }

SocialHook envoie chaque réponse sur la bonne plateforme automatiquement et l'enregistre dans le fil de discussion. Les échecs de réponse ne bloquent pas l'accusé de livraison — votre webhook est toujours marqué DELIVERED.

Protection contre le replay (requêtes signées)

Et ensuite