Référence API

API SIP Trunks

Créez et gérez les trunks SIP du tenant. Utilisez /sip-trunks/onboard pour la configuration SIP sortante standard : cela provisionne le trunk sortant, enregistre les numéros de caller ID et peut définir le trunk comme trunk par défaut du tenant en une seule opération tout-ou-rien.

URL de base: https://api.aethexai.com/api/v1
Endpoints: 7
Portées: sip_trunks:readsip_trunks:writephone_numbers:write

POST/sip-trunks/onboard

Configuration SIP sortante en une étape.

Onboarder un trunk SIP

Crée un trunk SIP sortant et enregistre ses numéros de caller ID E.164 en une seule requête. C'est le chemin nominal pour le SIP sortant BYO-carrier et requiert à la fois sip_trunks:write et phone_numbers:write. Si set_as_tenant_default vaut true, Aethex utilise ce trunk lorsqu'un appel ne se résout pas vers un trunk plus spécifique issu de l'enregistrement from_number. Si une étape échoue, Aethex annule le trunk et aucun enregistrement partiel de numéro de téléphone n'est validé.

Corps de la requête

namestringrequis
Nom d'affichage du trunk, 1-255 caractères en texte brut.
outbound_addressstringrequis
Hôte SIP du carrier ou host:port auquel Aethex envoie les INVITE.
numbersstring[]requis
De un à 100 numéros de caller ID à enregistrer sur ce trunk, au format E.164 (+14155557654) ou en chiffres seuls (14155557654) pour les opérateurs qui refusent le + initial. L'opérateur reçoit la valeur telle quelle.
auth_modestringoptionnel
digest (par défaut), ip_acl, ou digest_plus_ip_acl.
auth_usernamestringoptionnel
Nom d'utilisateur digest. Requis lorsque auth_mode inclut digest.
auth_passwordstringoptionnel
Mot de passe digest. Requis lorsque auth_mode inclut digest ; jamais retourné.
transportstringoptionnel
udp (par défaut), tcp, ou tls.
media_encryptionstringoptionnel
allow (par défaut), disable, ou require pour la négociation SRTP.
outbound_dial_formatstringoptionnel
Format de numérotation des destinations sortantes vers l'opérateur. e164 (par défaut) conserve le +E.164 ; digits retire le + initial ; national restitue le format de numérotation national du pays de destination (+15551234567 -> 05551234567, requis par certains opérateurs nationaux). N'utilisez national que pour les opérateurs mono-pays, car chaque destination est restituée dans le format national de son propre pays.
agent_idstringoptionnel
UUID de l'agent pour les appels entrants vers les numéros enregistrés.
inboundobjectoptionnel
Règles de routage de repli initiales pour les numéros enregistrés.
outbound_enabledbooleanoptionnel
Indique si les numéros enregistrés peuvent être utilisés comme valeurs from_number sortantes. Par défaut true.
destination_allowlistobjectoptionnel
Garde de numérotation sortante { "mode": "allowlist" | "blocklist", "entries": ["+1800"] }.
max_concurrent_callsintegeroptionnel
Plafond de concurrence par trunk. Par défaut 10. Les valeurs au-delà du plafond de la plateforme sont écrêtées.
calls_per_hour_limitintegeroptionnel
Plafond horaire facultatif des appels sortants de ce trunk. Omettez-le pour n'avoir aucun plafond horaire, le comportement par défaut. Les valeurs au-delà du plafond de la plateforme sont écrêtées.
set_as_tenant_defaultbooleanoptionnel
Définit ce trunk comme trunk sortant par défaut du tenant. Par défaut false.

Erreurs

400Contrat d'authentification sortante invalide

auth_mode, auth_username, auth_password et outbound_address sont incohérents.

Pour digest, envoyez le nom d'utilisateur et le mot de passe. Pour ip_acl, omettez les deux. Pour les deux contrôles, utilisez digest_plus_ip_acl.

404Agent introuvable

Le agent_id fourni n'appartient pas au compte.

Vérifiez l'ID de l'agent avec GET /agents, ou omettez agent_id.

409Numéro déjà enregistré

L'un des numéros demandés est déjà actif sur un compte.

Utilisez un autre numéro ou libérez d'abord l'enregistrement de numéro de téléphone existant.

422Erreur de validation

Un numéro n'est pas au format E.164, l'adresse sortante est invalide, ou un champ viole le schéma.

Utilisez + suivi de 1 à 15 chiffres pour les numéros et un hôte de carrier ou host:port pour outbound_address.

502Échec du provisionnement SIP

Le trunk SIP n'a pas pu être provisionné.

Réessayez après avoir vérifié l'état du service SIP. Un onboard échoué annule l'état partiel.

Requête

json

{
  "name": "Production carrier",
  "outbound_address": "sip.carrier.example.com:5060",
  "numbers": ["+14155551234"],
  "auth_mode": "digest",
  "auth_username": "aethex_outbound",
  "auth_password": "REDACTED",
  "transport": "udp",
  "media_encryption": "allow",
  "outbound_enabled": true,
  "set_as_tenant_default": true
}

201 Réponse

json

{
  "trunk": {
    "id": "11111111-1111-4111-8111-111111111111",
    "tenant_id": "tenant-uuid",
    "name": "Production carrier",
    "type": "outbound",
    "aethex_sip_trunk_id": "st_a1b2c3d4e5f6",
    "aethex_sip_dispatch_rule_id": null,
    "numbers": ["+14155551234"],
    "allowed_addresses": [],
    "auth_mode": "digest",
    "auth_username": "aethex_outbound",
    "outbound_address": "sip.carrier.example.com:5060",
    "transport": "udp",
    "media_encryption": "allow",
    "destination_allowlist": { "mode": "blocklist", "entries": [] },
    "max_concurrent_calls": 10,
    "calls_per_hour_limit": null,
    "status": "active",
    "suspended": false,
    "created_at": "2026-06-25T08:00:00Z"
  },
  "phone_numbers": [
    {
      "id": "pn-uuid",
      "phone_number": "+14155551234",
      "friendly_name": "Production carrier",
      "provider": "sip",
      "trunk_id": "11111111-1111-4111-8111-111111111111",
      "agent_id": null,
      "routing_rules": null,
      "outbound_enabled": true,
      "status": "active",
      "created_at": "2026-06-25T08:00:00Z"
    }
  ],
  "tenant_default_set": true
}

POST/sip-trunks

Création de trunk de plus bas niveau.

Créer un trunk SIP

Crée un trunk SIP entrant ou sortant sans l'enregistrement de numéro de téléphone en une étape réalisé par /sip-trunks/onboard. Pour les trunks sortants, créez les enregistrements de numéro de téléphone séparément avec POST /phone-numbers/sip/register. Pour les trunks entrants, Aethex crée aussi une règle de routage limitée au trunk afin que les appels entrants correspondants atteignent l'agent associé au numéro appelé.

Corps de la requête

namestringrequis
Nom d'affichage du trunk.
typestringrequis
inbound ou outbound.
numbersstring[]optionnel
Numéros associés au trunk, au format E.164 (+14155557654) ou en chiffres seuls (14155557654). Ce sont des formats de transmission : un trunk sortant présente numbers[0] tel quel à l'opérateur comme caller ID, et un trunk entrant fait correspondre le numéro appelé exactement comme l'opérateur l'envoie — indiquez les deux formes en cas de doute.
allowed_addressesstring[]optionnel
Adresses IP source de l'opérateur qui authentifient les appels entrants. Chaque entrée doit être une adresse IPv4 publique ou un bloc CIDR entre /24 et /32 (pas de plages privées, catch-all ou réservées).
auth_modestringoptionnel
digest (par défaut), ip_acl, digest_plus_ip_acl, ou register (opérateurs de type register ; trunks entrants uniquement).
outbound_authstringoptionnel
Trunks register uniquement : la façon dont le trunk sortant associé s'authentifie auprès de votre opérateur. proxy (par défaut) passe par le registrar en périphérie, qui répond au défi de l'opérateur — nécessaire lorsque l'opérateur lie les appels à l'adresse IP enregistrée. direct appelle l'opérateur directement avec les identifiants digest du trunk, ce qu'exigent les opérateurs dont les SBC répondent 482 Request Merged à une nouvelle tentative dans le même dialogue. Ignoré pour les autres modes d'authentification.
outbound_from_userstringoptionnel
Trunks register uniquement : ce que les appels sortants transmettent comme utilisateur SIP From. number (par défaut) envoie le numéro de l'appelant, ce qu'attendent les opérateurs. username envoie le nom de connexion et transmet le numéro dans P-Asserted-Identity ; un système téléphonique comme 3CX en a besoin pour associer l'appel à son utilisateur. À définir à la création du trunk ; il ne peut plus être modifié ensuite.
auth_usernamestringoptionnel
Nom d'utilisateur digest.
auth_passwordstringoptionnel
Mot de passe digest. Jamais retourné. Pour les trunks register, il est stocké chiffré pour le registrar ; pour les autres, il ne réside que dans le serveur SIP.
outbound_addressstringoptionnel
Requis pour les trunks sortants ; hôte de carrier ou host:port. Pour les trunks register, il s'agit de l'adresse du registrar de l'opérateur.
realmstringoptionnel
Trunks register uniquement : le domaine SIP de l'opérateur (realm d'authentification). Par défaut, l'hôte de outbound_address.
register_expiresintegeroptionnel
Trunks register uniquement : intervalle de rafraîchissement du REGISTER en secondes (par défaut 120, plage 30–3600).
transportstringoptionnel
udp, tcp, ou tls.
media_encryptionstringoptionnel
allow, disable, ou require.
outbound_dial_formatstringoptionnel
Format de numérotation des destinations sortantes vers l'opérateur. e164 (par défaut) conserve le +E.164 ; digits retire le + initial ; national restitue le format de numérotation national du pays de destination (+15551234567 -> 05551234567, requis par certains opérateurs nationaux). N'utilisez national que pour les opérateurs mono-pays, car chaque destination est restituée dans le format national de son propre pays.
destination_allowlistobjectoptionnel
Garde de numérotation sortante.
max_concurrent_callsintegeroptionnel
Plafond de concurrence par trunk. Les valeurs au-delà du plafond de la plateforme sont écrêtées.
calls_per_hour_limitintegeroptionnel
Plafond horaire facultatif des appels sortants de ce trunk. Omettez-le pour n'avoir aucun plafond horaire, le comportement par défaut. Les valeurs au-delà du plafond de la plateforme sont écrêtées.

Erreurs

400Contrat d'authentification sortante invalide

Les champs d'authentification sortante sont incomplets ou contradictoires.

Faites correspondre auth_mode aux identifiants attendus par votre carrier.

409Numéro appartenant à un autre compte

L'un des numbers est déjà enregistré sur un autre compte et ne peut pas être rattaché à votre trunk.

Utilisez un numéro appartenant à votre compte, ou libérez-le d'abord de l'autre compte.

422Erreur de validation

La requête ne correspond pas au schéma fermé.

Supprimez les champs inconnus et respectez les contraintes de champ documentées.

502Échec du provisionnement SIP

La périphérie SIP a rejeté la création du trunk ou de la règle de routage.

Réessayez après avoir vérifié l'état du service SIP.

Requête

json

{
  "name": "Carrier outbound",
  "type": "outbound",
  "numbers": ["+14155551234"],
  "auth_mode": "ip_acl",
  "outbound_address": "sip.carrier.example.com:5060",
  "transport": "udp",
  "media_encryption": "allow"
}

201 Réponse

json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "tenant_id": "tenant-uuid",
  "name": "Carrier outbound",
  "type": "outbound",
  "aethex_sip_trunk_id": "st_a1b2c3d4e5f6",
  "aethex_sip_dispatch_rule_id": null,
  "numbers": ["+14155551234"],
  "allowed_addresses": [],
  "auth_mode": "ip_acl",
  "auth_username": null,
  "outbound_address": "sip.carrier.example.com:5060",
  "transport": "udp",
  "media_encryption": "allow",
  "destination_allowlist": { "mode": "blocklist", "entries": [] },
  "max_concurrent_calls": 10,
  "calls_per_hour_limit": null,
  "status": "active",
    "suspended": false,
  "created_at": "2026-06-25T08:00:00Z"
}

GET/sip-trunks

Liste les trunks SIP du tenant.

Lister les trunks SIP

Retourne les trunks SIP visibles par le compte appelant, du plus récent au plus ancien. Les trunks désactivés sont inclus ; les trunks supprimés ne le sont pas.

Chemin & Requête

offsetintegeroptionnel
Nombre de résultats à ignorer. Par défaut 0.
limitintegeroptionnel
Nombre maximum de résultats par page. Par défaut 50, maximum 200.

Réponse

json

{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "tenant_id": "tenant-uuid",
      "name": "Carrier outbound",
      "type": "outbound",
      "aethex_sip_trunk_id": "st_a1b2c3d4e5f6",
      "aethex_sip_dispatch_rule_id": null,
      "numbers": ["+14155551234"],
      "allowed_addresses": [],
      "auth_mode": "ip_acl",
      "auth_username": null,
      "outbound_address": "sip.carrier.example.com:5060",
      "transport": "udp",
      "media_encryption": "allow",
      "destination_allowlist": { "mode": "blocklist", "entries": [] },
      "max_concurrent_calls": 10,
      "calls_per_hour_limit": null,
      "status": "active",
    "suspended": false,
      "created_at": "2026-06-25T08:00:00Z"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 50
}

GET/sip-trunks/:trunk_id

Récupère un trunk par ID.

Récupérer un trunk SIP

Retourne un seul trunk SIP non supprimé appartenant au compte appelant. Un trunk disabled est toujours retourné ; un trunk supprimé ne l'est pas.

Chemin & Requête

trunk_idstringrequis
UUID du trunk SIP.

Erreurs

404Trunk SIP introuvable

Aucun trunk non supprimé appartenant au tenant n'existe avec cet ID, ou il appartient à un autre compte.

Confirmez le trunk_id avec GET /sip-trunks pour la même clé API.

Réponse

json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "tenant_id": "tenant-uuid",
  "name": "Carrier outbound",
  "type": "outbound",
  "aethex_sip_trunk_id": "st_a1b2c3d4e5f6",
  "aethex_sip_dispatch_rule_id": null,
  "numbers": ["+14155551234"],
  "allowed_addresses": [],
  "auth_mode": "ip_acl",
  "auth_username": null,
  "outbound_address": "sip.carrier.example.com:5060",
  "transport": "udp",
  "media_encryption": "allow",
  "destination_allowlist": { "mode": "blocklist", "entries": [] },
  "max_concurrent_calls": 10,
  "calls_per_hour_limit": null,
  "status": "active",
    "suspended": false,
  "created_at": "2026-06-25T08:00:00Z"
}

PATCH/sip-trunks/:trunk_id

Met à jour la politique modifiable du trunk.

Mettre à jour un trunk SIP

Met à jour les champs de politique côté Aethex. Pour les trunks entrants, numbers et allowed_addresses sont aussi synchronisés vers la périphérie SIP. Pour les trunks sortants, modifier numbers ou allowed_addresses nécessite de créer un trunk de remplacement, car ces champs ne peuvent pas être mis à jour sur place sur un trunk sortant. Modifier auth_mode nécessite également un trunk de remplacement ; omettez-le des requêtes PATCH.

Chemin & Requête

trunk_idstringrequis
UUID du trunk SIP.

Corps de la requête

namestringoptionnel
Nom d'affichage mis à jour.
numbersstring[]optionnel
Trunks entrants uniquement ; remplace la liste des numéros du trunk.
allowed_addressesstring[]optionnel
Trunks entrants uniquement ; remplace la liste d'autorisation des sources du carrier.
destination_allowlistobjectoptionnel
Garde de numérotation sortante.
max_concurrent_callsintegeroptionnel
Plafond de concurrence par trunk. Les valeurs au-delà du plafond de la plateforme sont écrêtées.
calls_per_hour_limitintegeroptionnel
Plafond horaire des appels sortants de ce trunk. Envoyez null pour supprimer le plafond. Les valeurs au-delà du plafond de la plateforme sont écrêtées.
outbound_dial_formatstringoptionnel
Format de numérotation des destinations sortantes vers l'opérateur. e164 conserve le +E.164 ; digits retire le + initial ; national restitue le format de numérotation national du pays de destination (+15551234567 -> 05551234567, requis par certains opérateurs nationaux). N'utilisez national que pour les opérateurs mono-pays, car chaque destination est restituée dans le format national de son propre pays.
auth_modestringoptionnel
Modifie le contrat d'authentification du trunk : digest, ip_acl, digest_plus_ip_acl ou register. Envoyez dans la même requête les identifiants requis par le nouveau mode.
statusstringoptionnel
active ou disabled.

Erreurs

404Trunk SIP introuvable

Aucun trunk non supprimé appartenant au tenant n'existe avec cet ID, ou il appartient à un autre compte.

Confirmez le trunk_id avec GET /sip-trunks pour la même clé API.

422Remplacement requis

La requête modifie des champs immuables du trunk sortant ou auth_mode.

Créez un trunk de remplacement, migrez les numéros/valeurs par défaut, puis supprimez l'ancien trunk.

502Échec de la mise à jour SIP

La synchronisation des champs du trunk entrant vers la périphérie SIP a échoué.

Réessayez après avoir vérifié l'état du service SIP.

Requête

json

{
  "destination_allowlist": {
    "mode": "allowlist",
    "entries": ["+1800", "+1415"]
  },
  "max_concurrent_calls": 25
}

Réponse 200

json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "tenant_id": "tenant-uuid",
  "name": "Carrier outbound",
  "type": "outbound",
  "aethex_sip_trunk_id": "st_a1b2c3d4e5f6",
  "aethex_sip_dispatch_rule_id": null,
  "numbers": ["+14155551234"],
  "allowed_addresses": [],
  "auth_mode": "ip_acl",
  "auth_username": null,
  "outbound_address": "sip.carrier.example.com:5060",
  "transport": "udp",
  "media_encryption": "allow",
  "destination_allowlist": { "mode": "allowlist", "entries": ["+1800", "+1415"] },
  "max_concurrent_calls": 25,
  "calls_per_hour_limit": null,
  "status": "active",
    "suspended": false,
  "created_at": "2026-06-25T08:00:00Z"
}

PATCH/sip-trunks/:trunk_id/set-default-outbound

Définit le trunk de repli du tenant.

Définir le trunk sortant par défaut

Marque un trunk sortant actif comme trunk par défaut du tenant. Aethex utilise ce trunk lorsqu'un appel sortant ne se résout pas via un mappage from_number enregistré.

Chemin & Requête

trunk_idstringrequis
UUID du trunk SIP.

Erreurs

404Trunk SIP introuvable

Aucun trunk non supprimé appartenant au tenant n'existe avec cet ID, ou il appartient à un autre compte.

Confirmez le trunk_id avec GET /sip-trunks pour la même clé API.

422Pas un trunk sortant actif

Le trunk est entrant ou n'est pas actif.

Choisissez un trunk actif avec type: "outbound".

DELETE/sip-trunks/:trunk_id

Suppression logique d'un trunk du tenant.

Supprimer un trunk SIP

Effectue une suppression logique d'un trunk appartenant au tenant. L'endpoint est idempotent et retourne 204 même si le trunk était déjà supprimé, n'a jamais existé pour ce tenant, ou appartient à un autre tenant.

Chemin & Requête

trunk_idstringrequis
UUID du trunk SIP.