API Reference

Documentation complète de l'API VocalIA pour intégrer Voice Widget et Voice Telephony dans vos applications.

Authentification

L'API VocalIA utilise des clés API pour l'authentification. Incluez votre clé dans le header Authorization de chaque requête.

Authorization: Bearer voc_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Base URL

https://api.vocalia.ma/v1

https://sandbox.api.vocalia.ma/v1

Voice Widget - Intégration

Intégrez le Voice Widget en ajoutant simplement une balise script à votre page.

<!-- VocalIA Voice Widget -->
<script>
  window.VOCALIA_CONFIG = {
    tenant_id: 'votre-tenant-id',
    api_url: 'https://api.vocalia.ma',
    language: 'fr',
    position: 'bottom-right'
  };
</script>
<script src="https://vocalia.ma/voice-assistant/voice-widget-b2b.js" async></script>

Voice Widget - Configuration

Voice Widget - Événements

VocalIA.on('conversationStart', (data) => {
});

VocalIA.on('message', (data) => {
});

VocalIA.on('conversationEnd', (data) => {
});

VocalIA.on('error', (error) => {
  console.error('Erreur:', error.message);
});

POST Créer un appel

Initie un appel sortant vers un numéro de téléphone.

POST /v1/calls

Paramètres

Exemple de requête

curl -X POST https://api.vocalia.ma/v1/calls \
  -H "Authorization: Bearer voc_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+212612345678",
    "agentId": "agent_support_fr",
    "metadata": {
      "customerId": "cust_123",
      "orderId": "ord_456"
    }
  }'

Réponse

{
  "id": "call_abc123xyz",
  "status": "initiating",
  "to": "+212612345678",
  "from": "+212520123456",
  "agentId": "agent_support_fr",
  "createdAt": "2026-01-29T15:30:00Z",
  "metadata": {
    "customerId": "cust_123",
    "orderId": "ord_456"
  }
}

GET Récupérer un appel

GET /v1/calls/{call_id}

{
  "id": "call_abc123xyz",
  "status": "completed",
  "duration": 127,
  "to": "+212612345678",
  "from": "+212520123456",
  "transcript": [
    {"role": "agent", "content": "Bonjour, VocalIA..."},
    {"role": "user", "content": "Je voudrais..."}
  ],
  "sentiment": "positive",
  "cost": 0.13,
  "createdAt": "2026-01-29T15:30:00Z",
  "endedAt": "2026-01-29T15:32:07Z"
}

GET Lister les appels

GET /v1/calls?limit=20&status=completed&from=2026-01-01

Query Parameters

POST Transférer un appel

POST /v1/calls/{call_id}/transfer

{
  "to": "+212520999888",
  "message": "Je vous transfère vers un conseiller."
}

WS WebSocket - Connexion

Connexion WebSocket pour audio streaming bidirectionnel en temps réel.

wss://realtime.vocalia.ma/v1/stream?apiKey=voc_sk_live_xxxx

const ws = new WebSocket(
  'wss://realtime.vocalia.ma/v1/stream?apiKey=voc_sk_live_xxxx'
);

ws.onopen = () => {
  // Envoyer configuration initiale
  ws.send(JSON.stringify({
    type: 'config',
    agentId: 'agent_support_fr',
    language: 'fr',
    sampleRate: 16000
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'audio') {
    // Jouer l'audio de réponse
    playAudio(data.audio);
  }
};

WebSocket - Événements

Webhooks - Configuration

Configurez des webhooks pour recevoir des notifications en temps réel sur vos appels.

{
  "event": "call.completed",
  "timestamp": "2026-01-29T15:32:07Z",
  "data": {
    "callId": "call_abc123xyz",
    "duration": 127,
    "status": "completed",
    "sentiment": "positive",
    "leadScore": 85
  }
}

Webhooks - Types d'événements

Webhooks - Sécurité

Validez l'authenticité des webhooks avec la signature HMAC-SHA256.

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from('sha256=' + expected)
  );
}

AUTH Authentication Endpoints

User registration, login, JWT management, and password flows.

// Request
{ "email": "user@example.com",
  "password": "secure123",
  "name": "John Doe",
  "company": "Acme Corp",
  "plan": "pro" }

// Response 201
{ "success": true,
  "tenant": { "id": "acme_corp_k7m2", "api_key": "vk_a1b2c3..." },
  "provisioned": true }

TENANT Tenant Management

Multi-tenant configuration: origins, API keys, webhooks, usage, and GDPR compliance.

// Response
{ "plan": "pro",
  "quotas": {
    "calls": { "used": 42, "limit": 500, "pct": 8 },
    "sessions": { "used": 156, "limit": 2000, "pct": 8 }
  },
  "features_enabled": ["voice_widget", "cloud_voice", "webhooks"] }

BILLING Billing & Subscriptions

Stripe-powered billing: checkout sessions, subscriptions, portal, and usage-based metering.

KB Knowledge Base

Smart knowledge base with hybrid search and tenant isolation.

ECOM E-Commerce Catalog

WooCommerce/Shopify connector, semantic product search, AI recommendations, catalog sync, and cart recovery.

DATA Conversations & UCP

Conversation history, call recordings, unified customer profiles, and data export.

ADMIN Admin & Operations

System health, HITL moderation, telephony stats, NLP operator, and export.

Codes d'erreur

Rate Limits

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1706540400

SDKs & Libraries

require 'net/http'
require 'json'

uri = URI('https://api.vocalia.ma/respond')
res = Net::HTTP.post(uri,
  { message: 'Bonjour',
    language: 'fr',
    tenant_id: 'your_tenant'
  }.to_json,
  'Content-Type' => 'application/json',
  'Authorization' => "Bearer #{api_key}"
)
puts JSON.parse(res.body)

import ("bytes"; "net/http"; "encoding/json")

body, _ := json.Marshal(map[string]string{
  "message":   "Bonjour",
  "language":  "fr",
  "tenant_id": "your_tenant",
})
req, _ := http.NewRequest("POST",
  "https://api.vocalia.ma/respond",
  bytes.NewBuffer(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+apiKey)
resp, _ := http.DefaultClient.Do(req)