Documentation API complète pour gérer les trunks SIP et les numéros de téléphone par programmation. Automatisez votre infrastructure vocale grâce à l’API RESTful de VoxPria.
Authentification #
Toutes les requêtes API nécessitent une authentification à l’aide d’une clé API dans l’en-tête Authorization.
Obtenir votre clé API #
- Connectez-vous au tableau de bord VoxPria
- Accédez à Paramètres → Clés API
- Cliquez sur Générer une nouvelle clé
- Copiez-la et conservez-la en lieu sûr
- Utilisez-la dans l’en-tête Authorization
Format d’authentification #
`bash
Authorization: Bearer YOUR_API_KEY
`
Exemple de requête #
`bash
curl -X GET https://api.voxpria.com/v1/sip/trunks
-H « Authorization: Bearer vox_sk_test_abc123xyz789 »
`
URL de base #
`
https://api.voxpria.com/v1
`
Tous les points de terminaison sont relatifs à cette URL de base.
Trunks SIP #
Lister les trunks SIP #
Récupérez tous les trunks SIP de votre compte.
Point de terminaison : GET /sip/trunks
Réponse :
`json
{
« data »: [
{
« id »: « trunk_abc123 »,
« name »: « My ElevenLabs Trunk »,
« provider »: « elevenlabs »,
« status »: « active »,
« created_at »: « 2024-01-15T10:30:00Z »,
« phone_numbers_count »: 5
}
],
« pagination »: {
« page »: 1,
« per_page »: 20,
« total »: 3
}
}
`
Paramètres de requête :
page(entier) – Numéro de page (par défaut : 1)per_page(entier) – Résultats par page (par défaut : 20, max : 100)provider(chaîne) – Filtrer par type de fournisseur
Exemple :
`bash
curl -X GET « https://api.voxpria.com/v1/sip/trunks?provider=elevenlabs »
-H « Authorization: Bearer YOUR_API_KEY »
`
Créer un trunk SIP #
Créez une nouvelle connexion de trunk SIP.
Point de terminaison : POST /sip/trunks
Corps de la requête :
Trunk ElevenLabs :
`json
{
« name »: « Production ElevenLabs »,
« provider »: « elevenlabs »,
« credentials »: {
« username »: « your_elevenlabs_username »,
« password »: « your_elevenlabs_password »
},
« config »: {
« server »: « sip.rtc.elevenlabs.io »,
« port »: 5061,
« transport »: « tls »
}
}
`
Trunk OpenAI :
`json
{
« name »: « Production OpenAI »,
« provider »: « openai »,
« credentials »: {
« project_id »: « proj_abc123 »,
« api_key »: « sk-proj-xyz789 »,
« webhook_secret »: « whsec_def456 »
}
}
`
Trunk générique :
`json
{
« name »: « Custom SIP Provider »,
« provider »: « generic »,
« credentials »: {
« username »: « sip_username »,
« password »: « sip_password »
},
« config »: {
« server »: « sip.example.com »,
« port »: 5060,
« transport »: « tcp »
}
}
`
Réponse :
`json
{
« id »: « trunk_abc123 »,
« name »: « Production ElevenLabs »,
« provider »: « elevenlabs »,
« status »: « active »,
« created_at »: « 2024-01-15T10:30:00Z »
}
`
Codes de statut :
201 Created– Trunk créé avec succès400 Bad Request– Paramètres invalides401 Unauthorized– Clé API invalide409 Conflict– Le nom du trunk existe déjà
Obtenir un trunk SIP #
Récupérez les détails d’un trunk précis.
Point de terminaison : GET /sip/trunks/{trunk_id}
Réponse :
`json
{
« id »: « trunk_abc123 »,
« name »: « Production ElevenLabs »,
« provider »: « elevenlabs »,
« status »: « active »,
« config »: {
« server »: « sip.rtc.elevenlabs.io »,
« port »: 5061,
« transport »: « tls »
},
« phone_numbers »: [
{
« id »: « phone_def456 »,
« number »: « +12125551234 »,
« status »: « active »
}
],
« created_at »: « 2024-01-15T10:30:00Z »,
« updated_at »: « 2024-01-20T14:20:00Z »
}
`
Remarque : Les identifiants ne sont pas retournés, pour des raisons de sécurité.
Mettre à jour un trunk SIP #
Mettez à jour la configuration ou les identifiants d’un trunk.
Point de terminaison : PATCH /sip/trunks/{trunk_id}
Corps de la requête :
`json
{
« name »: « Updated Trunk Name »,
« credentials »: {
« password »: « new_password »
},
« config »: {
« transport »: « tls »
}
}
`
Réponse :
`json
{
« id »: « trunk_abc123 »,
« name »: « Updated Trunk Name »,
« provider »: « elevenlabs »,
« status »: « active »,
« updated_at »: « 2024-01-20T15:00:00Z »
}
`
Remarque : Après la mise à jour des identifiants, reprovisionnez les numéros de téléphone concernés.
Supprimer un trunk SIP #
Supprimez un trunk et retirez tous les numéros de téléphone associés.
Point de terminaison : DELETE /sip/trunks/{trunk_id}
Réponse :
`json
{
« success »: true,
« message »: « Trunk deleted successfully »
}
`
Codes de statut :
200 OK– Trunk supprimé404 Not Found– Le trunk n’existe pas409 Conflict– Le trunk a des numéros de téléphone actifs (à retirer d’abord)
Provisionner un trunk (OpenAI) #
Provisionnez un trunk OpenAI au niveau du projet.
Point de terminaison : POST /sip/trunks/{trunk_id}/provision
Réponse :
`json
{
« success »: true,
« status »: « provisioned »,
« provisioned_at »: « 2024-01-20T16:00:00Z »
}
`
Remarque : Requis uniquement pour les trunks OpenAI. Provisionne l’ensemble du projet.
Numéros de téléphone #
Lister les numéros de téléphone #
Récupérez tous les numéros de téléphone de votre compte.
Point de terminaison : GET /phone-numbers
Réponse :
`json
{
« data »: [
{
« id »: « phone_abc123 »,
« number »: « +12125551234 »,
« trunk_id »: « trunk_def456 »,
« engine »: « elevenlabs »,
« status »: « active »,
« agent_id »: « agent_ghi789 »,
« capabilities »: {
« inbound »: true,
« outbound »: true,
« campaigns »: true
},
« created_at »: « 2024-01-15T10:30:00Z »
}
],
« pagination »: {
« page »: 1,
« per_page »: 20,
« total »: 15
}
}
`
Paramètres de requête :
page(entier) – Numéro de pageper_page(entier) – Résultats par pagetrunk_id(chaîne) – Filtrer par trunkstatus(chaîne) – Filtrer par statut :active,inactive,provisioningengine(chaîne) – Filtrer par moteur :elevenlabs,openai
Importer un numéro de téléphone #
Ajoutez un numéro de téléphone à VoxPria.
Point de terminaison : POST /phone-numbers/import
Corps de la requête :
`json
{
« phone_number »: « +12125551234 »,
« trunk_id »: « trunk_abc123 »,
« engine »: « elevenlabs »,
« agent_id »: « agent_def456 »,
« config »: {
« first_message »: « Hello! How can I help you today? »,
« max_duration »: 3600,
« language »: « en-US »
}
}
`
Réponse :
`json
{
« id »: « phone_abc123 »,
« number »: « +12125551234 »,
« trunk_id »: « trunk_def456 »,
« engine »: « elevenlabs »,
« status »: « provisioning »,
« agent_id »: « agent_ghi789 »,
« created_at »: « 2024-01-20T10:00:00Z »
}
`
Codes de statut :
201 Created– Numéro importé avec succès400 Bad Request– Format de numéro de téléphone invalide409 Conflict– Le numéro existe déjà429 Too Many Requests– Limite de débit dépassée (10/minute)
Limitation du débit :
- Maximum de 10 importations par minute par utilisateur
- HTTP 429 retourné en cas de dépassement
- Attendez 60 secondes avant de réessayer
Obtenir un numéro de téléphone #
Récupérez les détails d’un numéro de téléphone précis.
Point de terminaison : GET /phone-numbers/{phone_id}
Réponse :
`json
{
« id »: « phone_abc123 »,
« number »: « +12125551234 »,
« trunk_id »: « trunk_def456 »,
« trunk_name »: « My ElevenLabs Trunk »,
« engine »: « elevenlabs »,
« status »: « active »,
« agent_id »: « agent_ghi789 »,
« agent_name »: « Customer Support Agent »,
« config »: {
« first_message »: « Hello! How can I help you today? »,
« max_duration »: 3600,
« language »: « en-US »
},
« capabilities »: {
« inbound »: true,
« outbound »: true,
« campaigns »: true,
« recordings »: true
},
« stats »: {
« total_calls »: 127,
« total_minutes »: 423.5,
« last_call_at »: « 2024-01-20T14:30:00Z »
},
« created_at »: « 2024-01-15T10:30:00Z »,
« updated_at »: « 2024-01-20T14:30:00Z »
}
`
Mettre à jour un numéro de téléphone #
Mettez à jour la configuration d’un numéro de téléphone.
Point de terminaison : PATCH /phone-numbers/{phone_id}
Corps de la requête :
`json
{
« agent_id »: « agent_new789 »,
« config »: {
« first_message »: « Updated greeting message »,
« max_duration »: 1800
}
}
`
Réponse :
`json
{
« id »: « phone_abc123 »,
« number »: « +12125551234 »,
« status »: « active »,
« agent_id »: « agent_new789 »,
« updated_at »: « 2024-01-20T16:00:00Z »
}
`
Supprimer un numéro de téléphone #
Retirez un numéro de téléphone de VoxPria.
Point de terminaison : DELETE /phone-numbers/{phone_id}
Réponse :
`json
{
« success »: true,
« message »: « Phone number deleted successfully »
}
`
Remarque : Ceci retire le numéro de VoxPria, mais n’annule pas l’abonnement auprès du fournisseur.
Provisionner un numéro de téléphone #
Provisionnez un numéro de téléphone (ElevenLabs uniquement).
Point de terminaison : POST /phone-numbers/{phone_id}/provision
Réponse :
`json
{
« success »: true,
« status »: « active »,
« provisioned_at »: « 2024-01-20T16:30:00Z »
}
`
Remarque : Requis après l’importation de numéros ElevenLabs. OpenAI utilise un provisionnement au niveau du projet.
Opérations en lot #
Reprovisionner tous les numéros (trunk) #
Reprovisionnez tous les numéros d’un trunk après une mise à jour des identifiants.
Point de terminaison : POST /sip/trunks/{trunk_id}/reprovision-all
Réponse :
`json
{
« success »: true,
« total_numbers »: 5,
« provisioned »: 5,
« failed »: 0
}
`
Importer des numéros en lot #
Importez plusieurs numéros à la fois.
Point de terminaison : POST /phone-numbers/bulk-import
Corps de la requête :
`json
{
« trunk_id »: « trunk_abc123 »,
« engine »: « elevenlabs »,
« numbers »: [
{
« phone_number »: « +12125551234 »,
« agent_id »: « agent_def456 »
},
{
« phone_number »: « +12125555678 »,
« agent_id »: « agent_def456 »
}
]
}
`
Réponse :
`json
{
« success »: true,
« imported »: 2,
« failed »: 0,
« results »: [
{
« phone_number »: « +12125551234 »,
« status »: « success »,
« id »: « phone_abc123 »
},
{
« phone_number »: « +12125555678 »,
« status »: « success »,
« id »: « phone_abc124 »
}
]
}
`
Limitation du débit :
- Assujetti aux limites de débit d’importation standards
- Les importations échouées ne comptent pas dans la limite
- Respecte la limite de 10 importations par minute
Journaux d’appels #
Lister les journaux d’appels #
Récupérez l’historique des appels de vos numéros de téléphone.
Point de terminaison : GET /calls
Réponse :
`json
{
« data »: [
{
« id »: « call_abc123 »,
« phone_number »: « +12125551234 »,
« direction »: « inbound »,
« from »: « +13035559876 »,
« to »: « +12125551234 »,
« agent_id »: « agent_def456 »,
« status »: « completed »,
« duration »: 127,
« started_at »: « 2024-01-20T14:00:00Z »,
« ended_at »: « 2024-01-20T14:02:07Z »,
« recording_url »: « https://recordings.voxpria.com/abc123.mp3 »,
« transcript_available »: true
}
],
« pagination »: {
« page »: 1,
« per_page »: 20,
« total »: 342
}
}
`
Paramètres de requête :
page(entier) – Numéro de pageper_page(entier) – Résultats par pagephone_number(chaîne) – Filtrer par numéro de téléphonedirection(chaîne) – Filtrer :inbound,outboundstatus(chaîne) – Filtrer :completed,failed,no-answerstart_date(chaîne) – Date ISO 8601 (p. ex.2024-01-15)end_date(chaîne) – Date ISO 8601
Exemple :
`bash
curl -X GET « https://api.voxpria.com/v1/calls?phone_number=%2B12125551234&start_date=2024-01-15 »
-H « Authorization: Bearer YOUR_API_KEY »
`
Obtenir les détails d’un appel #
Récupérez des renseignements détaillés sur un appel précis.
Point de terminaison : GET /calls/{call_id}
Réponse :
`json
{
« id »: « call_abc123 »,
« phone_number »: « +12125551234 »,
« direction »: « inbound »,
« from »: « +13035559876 »,
« to »: « +12125551234 »,
« agent_id »: « agent_def456 »,
« agent_name »: « Customer Support Agent »,
« status »: « completed »,
« duration »: 127,
« started_at »: « 2024-01-20T14:00:00Z »,
« ended_at »: « 2024-01-20T14:02:07Z »,
« recording_url »: « https://recordings.voxpria.com/abc123.mp3 »,
« transcript »: {
« segments »: [
{
« speaker »: « agent »,
« text »: « Hello! How can I help you today? »,
« timestamp »: « 2024-01-20T14:00:02Z »
},
{
« speaker »: « caller »,
« text »: « I need help with my account. »,
« timestamp »: « 2024-01-20T14:00:05Z »
}
]
},
« metadata »: {
« caller_location »: « Denver, CO »,
« call_quality »: « excellent »
}
}
`
Webhooks #
Configurez des webhooks pour recevoir des notifications en temps réel.
Événements de webhook #
Types d’événements disponibles :
call.started– Appel amorcécall.ended– Appel terminécall.failed– Échec de connexion de l’appelnumber.provisioned– Numéro provisionné avec succèstrunk.updated– Configuration du trunk modifiée
Charge utile du webhook #
Exemple de webhook call.ended :
`json
{
« event »: « call.ended »,
« timestamp »: « 2024-01-20T14:02:07Z »,
« data »: {
« call_id »: « call_abc123 »,
« phone_number »: « +12125551234 »,
« direction »: « inbound »,
« status »: « completed »,
« duration »: 127,
« recording_url »: « https://recordings.voxpria.com/abc123.mp3 »
}
}
`
Configurer un webhook #
Point de terminaison : POST /webhooks
Corps de la requête :
`json
{
« url »: « https://your-app.com/webhooks/voxpria »,
« events »: [« call.started », « call.ended »],
« secret »: « your_webhook_secret »
}
`
Réponse :
`json
{
« id »: « webhook_abc123 »,
« url »: « https://your-app.com/webhooks/voxpria »,
« events »: [« call.started », « call.ended »],
« status »: « active »,
« created_at »: « 2024-01-20T10:00:00Z »
}
`
Vérifier les signatures des webhooks #
Les webhooks comprennent l’en-tête X-VoxPria-Signature pour la vérification.
Exemple de vérification (Node.js) :
`javascript
const crypto = require(‘crypto’);
function verifyWebhook(payload, signature, secret) {
const hmac = crypto.createHmac(‘sha256’, secret);
const digest = hmac.update(JSON.stringify(payload)).digest(‘hex’);
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(digest)
);
}
`
Gestion des erreurs #
Format de réponse d’erreur #
`json
{
« error »: {
« code »: « invalid_phone_number »,
« message »: « Phone number must be in E.164 format »,
« details »: {
« field »: « phone_number »,
« provided »: « 2125551234 »
}
}
}
`
Codes d’erreur courants #
400 Bad Request :
invalid_phone_number– Format de numéro de téléphone incorrectinvalid_credentials– Identifiants SIP invalidesmissing_required_field– Champ requis non fourni
401 Unauthorized :
invalid_api_key– Clé API invalide ou expiréeapi_key_missing– Aucune clé API fournie
403 Forbidden :
insufficient_permissions– La clé API n’a pas les permissions requisesfeature_not_enabled– Fonctionnalités SIP non offertes dans le forfait
404 Not Found :
trunk_not_found– L’identifiant du trunk n’existe pasphone_not_found– Le numéro de téléphone n’existe pas
409 Conflict :
trunk_name_exists– Le nom du trunk est déjà utiliséphone_number_exists– Le numéro est déjà importé
429 Too Many Requests :
rate_limit_exceeded– Trop de requêtes, ralentissezimport_limit_exceeded– Limite de débit d’importation de numéros atteinte
500 Internal Server Error :
server_error– Problème de serveur interneprovisioning_failed– Échec du provisionnement chez le fournisseur
Limites de débit #
Limites actuelles #
| Point de terminaison | Limite | Fenêtre |
|———-|——-|——–|
| Importation de numéros | 10 requêtes | 1 minute |
| API générale | 1000 requêtes | 1 heure |
| Webhooks | 100 livraisons | 1 minute |
En-têtes de limite de débit #
`
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1234567890
`
Gérer les limites de débit #
Lorsque vous recevez un code HTTP 429 :
- Lisez l’en-tête
X-RateLimit-Reset - Attendez jusqu’à l’horodatage de réinitialisation
- Réessayez la requête
- Mettez en place un délai exponentiel
Exemple :
`javascript
async function importWithRetry(phoneNumber, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await importPhoneNumber(phoneNumber);
} catch (error) {
if (error.status === 429) {
const resetTime = error.headers[‘x-ratelimit-reset’];
const waitTime = resetTime – Date.now() / 1000;
await sleep(waitTime * 1000);
continue;
}
throw error;
}
}
}
`
Exemples de SDK #
Node.js #
`javascript
const VoxPria = require(‘@voxpria/sdk’);
const client = new VoxPria({
apiKey: ‘vox_sk_test_abc123’
});
// Create trunk
const trunk = await client.trunks.create({
name: ‘My ElevenLabs Trunk’,
provider: ‘elevenlabs’,
credentials: {
username: ‘username’,
password: ‘password’
}
});
// Import number
const phone = await client.phoneNumbers.import({
phoneNumber: ‘+12125551234’,
trunkId: trunk.id,
engine: ‘elevenlabs’,
agentId: ‘agent_abc123’
});
// Provision number
await client.phoneNumbers.provision(phone.id);
// List calls
const calls = await client.calls.list({
phoneNumber: ‘+12125551234’,
startDate: ‘2024-01-15’
});
`
Python #
`python
from voxpria import VoxPria
client = VoxPria(api_key=’vox_sk_test_abc123′)
Create trunk #
trunk = client.trunks.create(
name=’My ElevenLabs Trunk’,
provider=’elevenlabs’,
credentials={
‘username’: ‘username’,
‘password’: ‘password’
}
)
Import number #
phone = client.phone_numbers.import_number(
phone_number=’+12125551234′,
trunk_id=trunk.id,
engine=’elevenlabs’,
agent_id=’agent_abc123′
)
Provision number #
client.phone_numbers.provision(phone.id)
List calls #
calls = client.calls.list(
phone_number=’+12125551234′,
start_date=’2024-01-15′
)
`
Tests #
Environnement bac à sable #
Testez l’intégration API sans affecter la production :
`
Base URL: https://api.sandbox.voxpria.com/v1
`
Utilisez des clés API de test :
`
vox_sk_test_abc123xyz789
`
Identifiants de test #
Le bac à sable comprend des identifiants SIP de test :
- Nom d’utilisateur :
test_user - Mot de passe :
test_pass - Serveur :
sip.test.voxpria.com
Numéros de téléphone de test #
Utilisez ces numéros pour les tests :
+15555551234– Réussit toujours+15555551235– Échoue toujours au provisionnement+15555551236– Simule un provisionnement lent
Meilleures pratiques #
Clés API #
- Utilisez des clés distinctes pour le développement et la production
- Faites tourner les clés régulièrement
- Ne validez jamais les clés dans le contrôle de version
- Utilisez des variables d’environnement
Gestion des erreurs #
- Mettez en place une logique de nouvelle tentative avec délai exponentiel
- Journalisez les erreurs à des fins de débogage
- Gérez les limites de débit avec grâce
- Validez les données avant les appels API
Performance #
- Mettez en cache les données de trunks et de numéros de téléphone
- Utilisez la pagination pour les grands ensembles de résultats
- Regroupez les opérations lorsque possible
- Surveillez les temps de réponse de l’API
Sécurité #
- Utilisez HTTPS pour toutes les requêtes
- Vérifiez les signatures des webhooks
- Mettez en place une liste blanche d’adresses IP si disponible
- Surveillez l’utilisation de l’API pour détecter les anomalies
Soutien #
- Documentation API : https://voxpria.com/api
- Page de statut : https://status.voxpria.com
- Courriel de soutien : support@voxpria.com
- Forum communautaire : https://community.voxpria.com
Pour les problèmes API urgents, contactez le soutien avec :
- L’identifiant de la requête (tiré de la réponse d’erreur)
- L’horodatage de la requête
- Le comportement attendu par rapport au comportement observé
- Un exemple de code qui reproduit le problème
