Integrations

Les descriptions des endpoints et des champs restent en anglais, telles que l'API les publie. C'est un choix délibéré : vous lisez ici ce que vous verrez aussi dans les réponses.

GET /v1/agents/{name}/integrations#

Supported integrations as seen from an agent. Every integration kind with its state. Every current kind is project-wide (scope: project): the PBX (yeastar_crm) and the CRM (hubspot) are configured once for the project under /integrations; this list shows the same rows for convenience. Writes on this path for a project-wide kind act on the project row.

Paramètres

Réponses

Exemple de requête

curl "https://api.voiceland.ai/v1/agents/{name}/integrations" \
  -H "Authorization: Bearer VL_API_KEY"

Exemple de réponse

{
  "items": [
    {
      "auth_modes": [
        "bearer",
        "oauth2"
      ],
      "calls_logged": 17,
      "capabilities": [
        "contact_lookup",
        "contact_create",
        "call_journal",
        "call_popup",
        "recording_link",
        "ops_trigger"
      ],
      "category": "pbx",
      "client_id": "vlc_2ffa3f973bfcbb5aa82fafea",
      "configured": true,
      "contact_lookups": 42,
      "create_unknown_contacts": true,
      "created_at": "2026-09-14T10:00:00Z",
      "description": "Connect a Yeastar P-Series Cloud Edition PBX through its custom CRM template: callers are matched against the project's contacts, unknown callers can be added, every finished call is journalled to the contact, and operations agents with a \"call ended\" trigger run on it.",
      "enabled": true,
      "endpoints": {
        "authorize": "https://api.voiceland.ai/oauth/authorize",
        "calls": "https://api.voiceland.ai/v1/integrations/yeastar/calls",
        "contacts": "https://api.voiceland.ai/v1/integrations/yeastar/contacts",
        "template": "https://api.voiceland.ai/v1/integrations/yeastar_crm/template.xml",
        "token": "https://api.voiceland.ai/v1/integrations/oauth/token"
      },
      "kind": "yeastar_crm",
      "last_seen_at": "2026-09-15T06:45:31Z",
      "logo": "/v1/integrations/yeastar_crm/logo.svg",
      "name": "Yeastar P-Series Cloud PBX",
      "order": 1,
      "redirect_uris": [
        "https://example.com/integration/callback/api/crm/2df2ad9bbc084115bde6924892756da9/"
      ],
      "scope": "project",
      "secret_hint": "…gWc4",
      "vendor": "Yeastar"
    }
  ]
}

DELETE /v1/agents/{name}/integrations/{kind}#

Remove an integration. Deletes the OAuth client; every token it issued stops working. Journalled calls are kept.

Paramètres

Réponses

Exemple de requête

curl -X DELETE "https://api.voiceland.ai/v1/agents/{name}/integrations/{kind}" \
  -H "Authorization: Bearer VL_API_KEY"

PUT /v1/agents/{name}/integrations/{kind}#

Enable or configure an integration. The first call with enabled: true mints the OAuth client and answers 201 with client_secret, which is shown exactly once: store it in the other system at once. Later calls reconfigure (redirect_uris for the OAuth2 authorization-code flow, create_unknown_contacts to let the PBX add callers it does not find, authorize_base_url when the consent page lives on your own console host). Setting enabled: false revokes every token the client holds.

Paramètres

Corps de la requête

application/json Schéma : IntegrationRequest

Réponses

Exemple de requête

curl -X PUT "https://api.voiceland.ai/v1/agents/{name}/integrations/{kind}" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "create_unknown_contacts": true,
  "enabled": true,
  "redirect_uris": [
    "https://example.com/integration/callback/api/crm/2df2ad9bbc084115bde6924892756da9/"
  ]
}'

Une réponse réussie renvoie un IntegrationView.

Exemple de réponse

{
  "auth_modes": [
    "bearer",
    "oauth2"
  ],
  "calls_logged": 17,
  "capabilities": [
    "contact_lookup",
    "contact_create",
    "call_journal",
    "call_popup",
    "recording_link",
    "ops_trigger"
  ],
  "category": "pbx",
  "client_id": "vlc_2ffa3f973bfcbb5aa82fafea",
  "client_secret": "vls_Q1w2E3r4T5y6U7i8O9p0A1s2D3f4G5h6J7k8L9z0X1c2V3b4",
  "configured": true,
  "contact_lookups": 42,
  "create_unknown_contacts": true,
  "created_at": "2026-09-14T10:00:00Z",
  "description": "Connect a Yeastar P-Series Cloud Edition PBX through its custom CRM template: callers are matched against the project's contacts, unknown callers can be added, every finished call is journalled to the contact, and operations agents with a \"call ended\" trigger run on it.",
  "enabled": true,
  "endpoints": {
    "authorize": "https://api.voiceland.ai/oauth/authorize",
    "calls": "https://api.voiceland.ai/v1/integrations/yeastar/calls",
    "contacts": "https://api.voiceland.ai/v1/integrations/yeastar/contacts",
    "template": "https://api.voiceland.ai/v1/integrations/yeastar_crm/template.xml",
    "token": "https://api.voiceland.ai/v1/integrations/oauth/token"
  },
  "kind": "yeastar_crm",
  "last_seen_at": "2026-09-15T06:45:31Z",
  "logo": "/v1/integrations/yeastar_crm/logo.svg",
  "name": "Yeastar P-Series Cloud PBX",
  "order": 1,
  "redirect_uris": [
    "https://example.com/integration/callback/api/crm/2df2ad9bbc084115bde6924892756da9/"
  ],
  "scope": "project",
  "secret_hint": "…gWc4",
  "vendor": "Yeastar"
}

POST /v1/agents/{name}/integrations/{kind}/authorize#

Grant access (OAuth2 consent). The consent step of the authorization-code flow, called by the console after the signed-in user allowed the request: mints a single-use code (10 minutes) bound to the client and to a registered redirect_uri and returns the URL to send the browser to. With one registered URI, redirect_uri may be omitted.

Paramètres

Corps de la requête

application/json

Réponses

Exemple de requête

curl -X POST "https://api.voiceland.ai/v1/agents/{name}/integrations/{kind}/authorize" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "redirect_uri": "https://example.com/integration/callback/api/crm/2df2ad9bbc084115bde6924892756da9/",
  "state": "8f1c"
}'

Exemple de réponse

{
  "expires_in": 600,
  "redirect_url": "https://example.com/integration/callback/api/crm/2df2ad9bbc084115bde6924892756da9/?code=vic_…&state=8f1c"
}

GET /v1/agents/{name}/integrations/{kind}/events#

What the other system sent. The calls the PBX journalled for this agent, newest first.

Paramètres

Réponses

Exemple de requête

curl "https://api.voiceland.ai/v1/agents/{name}/integrations/{kind}/events" \
  -H "Authorization: Bearer VL_API_KEY"

Exemple de réponse

{
  "items": [
    {
      "agent": "front-desk",
      "callee_name": "Front desk",
      "callee_number": "401",
      "caller_name": "Maria Papadopoulou",
      "caller_number": "+306972605774",
      "contact_id": "ct-3d60ba7619c2a4f1",
      "contact_number": "+306972605774",
      "description": "Call: 15/09/2026 09:45:24 Incoming Call from Maria Papadopoulou<+306972605774> to Front desk<401> 00:00:06",
      "direction": "inbound",
      "duration_raw": "00:00:06",
      "duration_sec": 6,
      "external_id": "1789454724",
      "id": "ic-9a1b2c3d4e5f6071",
      "kind": "yeastar_crm",
      "received_at": "2026-09-15T06:45:31Z",
      "recording": true,
      "recording_url": "https://example.com/api/v1.0/crm/recording?secret=…",
      "started_at": "2026-09-15T06:45:24Z",
      "started_raw": "15/09/2026 09:45:24",
      "status": "Incoming Call",
      "subject": "Extension Call"
    }
  ]
}

GET /v1/agents/{name}/integrations/{kind}/requests#

What the other system actually sent. Every request the other system sent to the integration endpoints, as it arrived, with the answer it got: method, path, query and headers (an allow-list; the Authorization header as its scheme only), the body and the answer (both capped at 16 KB), the status, the time taken and what it produced. It is the log the call journal cannot be: a lookup that matched nobody, a create that was refused, a journal rejected as invalid and an authentication that failed all appear here and nowhere else. Credentials are masked before the row is written. Rows are kept 30 days.

Paramètres

Réponses

Exemple de requête

curl "https://api.voiceland.ai/v1/agents/{name}/integrations/{kind}/requests" \
  -H "Authorization: Bearer VL_API_KEY"

Exemple de réponse

{
  "items": [
    {
      "agent": "_project",
      "body": "{\"CallId\":\"1727000000\",\"CallerNumber\":\"+302101234567\",\"CalleeNumber\":\"401\",\"Direction\":\"Inbound\",\"Duration\":\"00:00:42\"}",
      "body_bytes": 142,
      "client_id": "vlc_f02fdf34fc14827aea43c66d",
      "contact_id": "ct-91ab20",
      "duration_ms": 38,
      "event_id": "ic-3b77e1",
      "headers": {
        "Authorization": "Bearer •••",
        "Content-Type": "application/json",
        "User-Agent": "Yeastar-PBX/83.16.0.29"
      },
      "id": "ir-9f3a2c",
      "kind": "yeastar_crm",
      "method": "POST",
      "outcome": "ok",
      "path": "/v1/integrations/yeastar/calls",
      "received_at": "2026-09-23T10:15:03Z",
      "remote_ip": "203.0.113.10",
      "scenario": "call_journal",
      "status": 201
    }
  ],
  "retention_days": 30
}

POST /v1/agents/{name}/integrations/{kind}/rotate-secret#

Rotate the client secret. Mints a new secret (returned once) and revokes every token issued under the old one.

Paramètres

Réponses

Exemple de requête

curl -X POST "https://api.voiceland.ai/v1/agents/{name}/integrations/{kind}/rotate-secret" \
  -H "Authorization: Bearer VL_API_KEY"

Une réponse réussie renvoie un IntegrationView.

Exemple de réponse

{
  "auth_modes": [
    "bearer",
    "oauth2"
  ],
  "calls_logged": 17,
  "capabilities": [
    "contact_lookup",
    "contact_create",
    "call_journal",
    "call_popup",
    "recording_link",
    "ops_trigger"
  ],
  "category": "pbx",
  "client_id": "vlc_2ffa3f973bfcbb5aa82fafea",
  "client_secret": "vls_Q1w2E3r4T5y6U7i8O9p0A1s2D3f4G5h6J7k8L9z0X1c2V3b4",
  "configured": true,
  "contact_lookups": 42,
  "create_unknown_contacts": true,
  "created_at": "2026-09-14T10:00:00Z",
  "description": "Connect a Yeastar P-Series Cloud Edition PBX through its custom CRM template: callers are matched against the project's contacts, unknown callers can be added, every finished call is journalled to the contact, and operations agents with a \"call ended\" trigger run on it.",
  "enabled": true,
  "endpoints": {
    "authorize": "https://api.voiceland.ai/oauth/authorize",
    "calls": "https://api.voiceland.ai/v1/integrations/yeastar/calls",
    "contacts": "https://api.voiceland.ai/v1/integrations/yeastar/contacts",
    "template": "https://api.voiceland.ai/v1/integrations/yeastar_crm/template.xml",
    "token": "https://api.voiceland.ai/v1/integrations/oauth/token"
  },
  "kind": "yeastar_crm",
  "last_seen_at": "2026-09-15T06:45:31Z",
  "logo": "/v1/integrations/yeastar_crm/logo.svg",
  "name": "Yeastar P-Series Cloud PBX",
  "order": 1,
  "redirect_uris": [
    "https://example.com/integration/callback/api/crm/2df2ad9bbc084115bde6924892756da9/"
  ],
  "scope": "project",
  "secret_hint": "…gWc4",
  "vendor": "Yeastar"
}

GET /v1/agents/{name}/integrations/{kind}/template.xml#

Download the template for the other system. For yeastar_crm: the custom CRM template XML, pre-filled with this deployment's endpoints, to upload under Integrations > CRM > Template Management on the PBX. ?auth=bearer (default) authenticates with the client credentials and needs no browser step; ?auth=oauth2 uses the authorization-code flow through the console's consent page.

Paramètres

Réponses

Exemple de requête

curl "https://api.voiceland.ai/v1/agents/{name}/integrations/{kind}/template.xml" \
  -H "Authorization: Bearer VL_API_KEY"

GET /v1/httpactions#

List HTTP actions. Reusable HTTP request templates your agents can call.

Réponses

Exemple de requête

curl "https://api.voiceland.ai/v1/httpactions" \
  -H "Authorization: Bearer VL_API_KEY"

Exemple de réponse

{
  "items": []
}

POST /v1/httpactions#

Create an HTTP action. Creates a reusable, parameterised HTTP request. Reference secrets with ${secret:NAME} and inputs with ${var}.

Corps de la requête

application/json Schéma : Action

Réponses

Exemple de requête

curl -X POST "https://api.voiceland.ai/v1/httpactions" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "headers": {
    "Authorization": "Bearer ${secret:crm_token}"
  },
  "id": "lookup-customer",
  "inputs": [
    {
      "name": "phone",
      "required": true,
      "type": "string"
    }
  ],
  "method": "GET",
  "name": "Lookup customer by phone",
  "url": "https://example.com/customers?phone=${phone}"
}'

Exemple de réponse

{
  "id": "lookup-customer",
  "method": "GET"
}

DELETE /v1/httpactions/{id}#

Delete an HTTP action. Deletes an action.

Paramètres

Réponses

Exemple de requête

curl -X DELETE "https://api.voiceland.ai/v1/httpactions/{id}" \
  -H "Authorization: Bearer VL_API_KEY"

GET /v1/httpactions/{id}#

Get an HTTP action. Returns one action by id.

Paramètres

Réponses

Exemple de requête

curl "https://api.voiceland.ai/v1/httpactions/{id}" \
  -H "Authorization: Bearer VL_API_KEY"

Exemple de réponse

{
  "id": "lookup-customer",
  "method": "GET"
}

PUT /v1/httpactions/{id}#

Update an HTTP action. Replaces an action; the id in the path wins.

Paramètres

Corps de la requête

application/json Schéma : Action

Réponses

Exemple de requête

curl -X PUT "https://api.voiceland.ai/v1/httpactions/{id}" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "headers": {
    "Authorization": "Bearer ${secret:crm_token}"
  },
  "id": "lookup-customer",
  "inputs": [
    {
      "name": "phone",
      "required": true,
      "type": "string"
    }
  ],
  "method": "GET",
  "name": "Lookup customer by phone",
  "url": "https://example.com/customers?phone=${phone}"
}'

Exemple de réponse

{
  "id": "lookup-customer"
}

GET /v1/httpflows#

List HTTP flows. Ordered chains of actions.

Réponses

Exemple de requête

curl "https://api.voiceland.ai/v1/httpflows" \
  -H "Authorization: Bearer VL_API_KEY"

Exemple de réponse

{
  "items": []
}

POST /v1/httpflows#

Create an HTTP flow. Creates an ordered chain of actions with per-step variable extraction.

Corps de la requête

application/json Schéma : Flow

Réponses

Exemple de requête

curl -X POST "https://api.voiceland.ai/v1/httpflows" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "order-status",
  "inputs": [
    {
      "name": "phone",
      "required": true,
      "type": "string"
    }
  ],
  "name": "Order status",
  "outputs": [
    {
      "name": "order_id"
    }
  ],
  "steps": [
    {
      "action_id": "lookup-customer",
      "extract": [
        {
          "from": "data.id",
          "var": "order_id"
        }
      ]
    }
  ]
}'

Exemple de réponse

{
  "id": "order-status"
}

DELETE /v1/httpflows/{id}#

Delete an HTTP flow. Deletes a flow.

Paramètres

Réponses

Exemple de requête

curl -X DELETE "https://api.voiceland.ai/v1/httpflows/{id}" \
  -H "Authorization: Bearer VL_API_KEY"

GET /v1/httpflows/{id}#

Get an HTTP flow. Returns one flow by id.

Paramètres

Réponses

Exemple de requête

curl "https://api.voiceland.ai/v1/httpflows/{id}" \
  -H "Authorization: Bearer VL_API_KEY"

Exemple de réponse

{
  "id": "order-status"
}

PUT /v1/httpflows/{id}#

Update an HTTP flow. Replaces a flow; the id in the path wins.

Paramètres

Corps de la requête

application/json Schéma : Flow

Réponses

Exemple de requête

curl -X PUT "https://api.voiceland.ai/v1/httpflows/{id}" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "order-status",
  "inputs": [
    {
      "name": "phone",
      "required": true,
      "type": "string"
    }
  ],
  "name": "Order status",
  "outputs": [
    {
      "name": "order_id"
    }
  ],
  "steps": [
    {
      "action_id": "lookup-customer",
      "extract": [
        {
          "from": "data.id",
          "var": "order_id"
        }
      ]
    }
  ]
}'

Exemple de réponse

{
  "id": "order-status"
}

POST /v1/httpflows/{id}/execute#

Run a flow. Executes a flow with the supplied inputs and returns the collected variables + per-step audit. A failed step returns 502 with a partial result.

Paramètres

Corps de la requête

application/json

Réponses

Exemple de requête

curl -X POST "https://api.voiceland.ai/v1/httpflows/{id}/execute" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "inputs": {
    "phone": "+30693XXXXXXX"
  }
}'

Exemple de réponse

{
  "steps": [],
  "vars": {
    "eta": "tomorrow",
    "order_id": "4471"
  }
}

GET /v1/integrations#

Integrations catalog with the project-wide state. Every supported integration with its state for the project. yeastar_crm (the PBX) carries its OAuth client, redirect URIs, endpoints and activity; hubspot (the CRM) its token state, schedule and policies. logo is a public brand mark at /v1/integrations/{kind}/logo.svg.

Réponses

Exemple de requête

curl "https://api.voiceland.ai/v1/integrations" \
  -H "Authorization: Bearer VL_API_KEY"

Exemple de réponse

{
  "items": [
    {
      "auth_modes": [
        "bearer",
        "oauth2"
      ],
      "calls_logged": 17,
      "capabilities": [
        "contact_lookup",
        "contact_create",
        "call_journal",
        "call_popup",
        "recording_link",
        "ops_trigger"
      ],
      "category": "pbx",
      "client_id": "vlc_2ffa3f973bfcbb5aa82fafea",
      "configured": true,
      "contact_lookups": 42,
      "create_unknown_contacts": true,
      "created_at": "2026-09-14T10:00:00Z",
      "description": "Connect a Yeastar P-Series Cloud Edition PBX through its custom CRM template: callers are matched against the project's contacts, unknown callers can be added, every finished call is journalled to the contact, and operations agents with a \"call ended\" trigger run on it.",
      "enabled": true,
      "endpoints": {
        "authorize": "https://api.voiceland.ai/oauth/authorize",
        "calls": "https://api.voiceland.ai/v1/integrations/yeastar/calls",
        "contacts": "https://api.voiceland.ai/v1/integrations/yeastar/contacts",
        "template": "https://api.voiceland.ai/v1/integrations/yeastar_crm/template.xml",
        "token": "https://api.voiceland.ai/v1/integrations/oauth/token"
      },
      "kind": "yeastar_crm",
      "last_seen_at": "2026-09-15T06:45:31Z",
      "logo": "/v1/integrations/yeastar_crm/logo.svg",
      "name": "Yeastar P-Series Cloud PBX",
      "order": 1,
      "redirect_uris": [
        "https://example.com/integration/callback/api/crm/2df2ad9bbc084115bde6924892756da9/"
      ],
      "scope": "project",
      "secret_hint": "…gWc4",
      "vendor": "Yeastar"
    },
    {
      "auth_modes": [
        "private_app_token"
      ],
      "capabilities": [
        "contact_pull",
        "contact_push",
        "push_on_create",
        "conflict_policy"
      ],
      "category": "crm",
      "configured": true,
      "conflict_policy": "merge",
      "created_at": "2026-09-18T10:00:00Z",
      "enabled": true,
      "has_token": true,
      "kind": "hubspot",
      "last_pull_at": "2026-09-19T08:00:04Z",
      "last_run_at": "2026-09-19T08:00:04Z",
      "logo": "/v1/integrations/hubspot/logo.svg",
      "name": "HubSpot CRM",
      "next_pull_at": "2026-09-19T08:30:04Z",
      "order": 2,
      "portal_id": "424242",
      "pull_interval_min": 30,
      "push_interval_min": 0,
      "push_mode": "missing_only",
      "push_on_create": true,
      "scope": "project",
      "vendor": "HubSpot"
    }
  ]
}

DELETE /v1/integrations/{kind}#

Remove a project integration. Deletes the configuration (the PBX's OAuth client, or the CRM's stored token). Journalled calls and synced contacts are kept.

Paramètres

Réponses

Exemple de requête

curl -X DELETE "https://api.voiceland.ai/v1/integrations/{kind}" \
  -H "Authorization: Bearer VL_API_KEY"

PUT /v1/integrations/{kind}#

Configure a project integration. For yeastar_crm the body is the PBX request: the first call with enabled: true mints the OAuth client and answers 201 with client_secret (shown once); later calls set redirect_uris, create_unknown_contacts, authorize_base_url; enabled: false revokes every token. For hubspot: token is the private-app access token (scopes crm.objects.contacts.read and crm.objects.contacts.write), write-only and verified against HubSpot before it is stored (400 hubspot_auth otherwise); pull_interval_min / push_interval_min are 0 (off) or at least 10; conflict_policy: merge (default), hubspot_wins, local_wins, create_new; push_mode: missing_only (default) or force_all; enabled: true needs a token.

Paramètres

Corps de la requête

application/json Schéma : ProjectIntegrationRequest

Réponses

Exemple de requête

curl -X PUT "https://api.voiceland.ai/v1/integrations/{kind}" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "conflict_policy": "merge",
  "enabled": true,
  "pull_interval_min": 30,
  "push_interval_min": 0,
  "push_mode": "missing_only",
  "push_on_create": true,
  "token": "pat-eu1-…"
}'

Une réponse réussie renvoie un ProjectIntegrationView.

Exemple de réponse

{
  "auth_modes": [
    "private_app_token"
  ],
  "capabilities": [
    "contact_pull",
    "contact_push",
    "push_on_create",
    "conflict_policy"
  ],
  "category": "crm",
  "configured": true,
  "conflict_policy": "merge",
  "created_at": "2026-09-18T10:00:00Z",
  "enabled": true,
  "has_token": true,
  "kind": "hubspot",
  "last_pull_at": "2026-09-19T08:00:04Z",
  "last_run_at": "2026-09-19T08:00:04Z",
  "logo": "/v1/integrations/hubspot/logo.svg",
  "name": "HubSpot CRM",
  "next_pull_at": "2026-09-19T08:30:04Z",
  "order": 2,
  "portal_id": "424242",
  "pull_interval_min": 30,
  "push_interval_min": 0,
  "push_mode": "missing_only",
  "push_on_create": true,
  "scope": "project",
  "vendor": "HubSpot"
}

POST /v1/integrations/{kind}/authorize#

Grant the PBX access (OAuth2 consent). The consent step of the authorization-code flow, called by the console after the signed-in user allowed the request: mints a single-use code bound to the client and to a registered redirect_uri and returns the URL to send the browser to.

Paramètres

Corps de la requête

application/json

Réponses

Exemple de requête

curl -X POST "https://api.voiceland.ai/v1/integrations/{kind}/authorize" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "redirect_uri": "https://example.com/integration/callback/api/crm/2df2ad9bbc084115bde6924892756da9/",
  "state": "8f1c"
}'

Exemple de réponse

{
  "expires_in": 600,
  "redirect_url": "https://example.com/integration/callback/api/crm/2df2ad9bbc084115bde6924892756da9/?code=vic_…&state=8f1c"
}

GET /v1/integrations/{kind}/events#

What the PBX sent. The calls the PBX journalled for the project, newest first.

Paramètres

Réponses

Exemple de requête

curl "https://api.voiceland.ai/v1/integrations/{kind}/events" \
  -H "Authorization: Bearer VL_API_KEY"

Exemple de réponse

{
  "items": [
    {
      "agent": "front-desk",
      "callee_name": "Front desk",
      "callee_number": "401",
      "caller_name": "Maria Papadopoulou",
      "caller_number": "+306972605774",
      "contact_id": "ct-3d60ba7619c2a4f1",
      "contact_number": "+306972605774",
      "description": "Call: 15/09/2026 09:45:24 Incoming Call from Maria Papadopoulou<+306972605774> to Front desk<401> 00:00:06",
      "direction": "inbound",
      "duration_raw": "00:00:06",
      "duration_sec": 6,
      "external_id": "1789454724",
      "id": "ic-9a1b2c3d4e5f6071",
      "kind": "yeastar_crm",
      "received_at": "2026-09-15T06:45:31Z",
      "recording": true,
      "recording_url": "https://example.com/api/v1.0/crm/recording?secret=…",
      "started_at": "2026-09-15T06:45:24Z",
      "started_raw": "15/09/2026 09:45:24",
      "status": "Incoming Call",
      "subject": "Extension Call"
    }
  ]
}

GET /v1/integrations/{kind}/requests#

What the PBX actually sent. Every request the other system sent to the integration endpoints, as it arrived, with the answer it got: method, path, query and headers (an allow-list; the Authorization header as its scheme only), the body and the answer (both capped at 16 KB), the status, the time taken and what it produced. It is the log the call journal cannot be: a lookup that matched nobody, a create that was refused, a journal rejected as invalid and an authentication that failed all appear here and nowhere else. Credentials are masked before the row is written. Rows are kept 30 days.

Paramètres

Réponses

Exemple de requête

curl "https://api.voiceland.ai/v1/integrations/{kind}/requests" \
  -H "Authorization: Bearer VL_API_KEY"

Exemple de réponse

{
  "items": [
    {
      "agent": "_project",
      "body": "{\"CallId\":\"1727000000\",\"CallerNumber\":\"+302101234567\",\"CalleeNumber\":\"401\",\"Direction\":\"Inbound\",\"Duration\":\"00:00:42\"}",
      "body_bytes": 142,
      "client_id": "vlc_f02fdf34fc14827aea43c66d",
      "contact_id": "ct-91ab20",
      "duration_ms": 38,
      "event_id": "ic-3b77e1",
      "headers": {
        "Authorization": "Bearer •••",
        "Content-Type": "application/json",
        "User-Agent": "Yeastar-PBX/83.16.0.29"
      },
      "id": "ir-9f3a2c",
      "kind": "yeastar_crm",
      "method": "POST",
      "outcome": "ok",
      "path": "/v1/integrations/yeastar/calls",
      "received_at": "2026-09-23T10:15:03Z",
      "remote_ip": "203.0.113.10",
      "scenario": "call_journal",
      "status": 201
    }
  ],
  "retention_days": 30
}

POST /v1/integrations/{kind}/rotate-secret#

Rotate the PBX client secret. For yeastar_crm: mints a new secret (returned once) and revokes every token issued under the old one.

Paramètres

Réponses

Exemple de requête

curl -X POST "https://api.voiceland.ai/v1/integrations/{kind}/rotate-secret" \
  -H "Authorization: Bearer VL_API_KEY"

Une réponse réussie renvoie un IntegrationView.

Exemple de réponse

{
  "auth_modes": [
    "bearer",
    "oauth2"
  ],
  "calls_logged": 17,
  "capabilities": [
    "contact_lookup",
    "contact_create",
    "call_journal",
    "call_popup",
    "recording_link",
    "ops_trigger"
  ],
  "category": "pbx",
  "client_id": "vlc_2ffa3f973bfcbb5aa82fafea",
  "client_secret": "vls_Q1w2E3r4T5y6U7i8O9p0A1s2D3f4G5h6J7k8L9z0X1c2V3b4",
  "configured": true,
  "contact_lookups": 42,
  "create_unknown_contacts": true,
  "created_at": "2026-09-14T10:00:00Z",
  "description": "Connect a Yeastar P-Series Cloud Edition PBX through its custom CRM template: callers are matched against the project's contacts, unknown callers can be added, every finished call is journalled to the contact, and operations agents with a \"call ended\" trigger run on it.",
  "enabled": true,
  "endpoints": {
    "authorize": "https://api.voiceland.ai/oauth/authorize",
    "calls": "https://api.voiceland.ai/v1/integrations/yeastar/calls",
    "contacts": "https://api.voiceland.ai/v1/integrations/yeastar/contacts",
    "template": "https://api.voiceland.ai/v1/integrations/yeastar_crm/template.xml",
    "token": "https://api.voiceland.ai/v1/integrations/oauth/token"
  },
  "kind": "yeastar_crm",
  "last_seen_at": "2026-09-15T06:45:31Z",
  "logo": "/v1/integrations/yeastar_crm/logo.svg",
  "name": "Yeastar P-Series Cloud PBX",
  "order": 1,
  "redirect_uris": [
    "https://example.com/integration/callback/api/crm/2df2ad9bbc084115bde6924892756da9/"
  ],
  "scope": "project",
  "secret_hint": "…gWc4",
  "vendor": "Yeastar"
}

GET /v1/integrations/{kind}/runs#

Sync history. Runs newest first: direction, trigger (schedule, manual, on_create), status and the counts of contacts read, created, updated, linked, left unchanged and failed. Kept for 30 days.

Paramètres

Réponses

Exemple de requête

curl "https://api.voiceland.ai/v1/integrations/{kind}/runs" \
  -H "Authorization: Bearer VL_API_KEY"

Exemple de réponse

{
  "items": [
    {
      "created": 4,
      "direction": "pull",
      "failed": 0,
      "fetched": 312,
      "finished_at": "2026-09-19T08:00:04Z",
      "id": "run-9a1b2c3d4e5f6071",
      "kind": "hubspot",
      "linked": 2,
      "skipped": 305,
      "started_at": "2026-09-19T08:00:00Z",
      "status": "ok",
      "trigger": "schedule",
      "updated": 1
    }
  ]
}

POST /v1/integrations/{kind}/sync#

Run a sync once. Queues a one-time pull (HubSpot to contacts) or push (contacts to HubSpot); it starts within a minute on one node. 409 sync_in_progress while a run is queued or running; 409 not_enabled before the integration is enabled.

Paramètres

Corps de la requête

application/json

Réponses

Exemple de requête

curl -X POST "https://api.voiceland.ai/v1/integrations/{kind}/sync" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "direction": "pull"
}'

Exemple de réponse

{
  "direction": "pull",
  "integration": {
    "auth_modes": [
      "private_app_token"
    ],
    "capabilities": [
      "contact_pull",
      "contact_push",
      "push_on_create",
      "conflict_policy"
    ],
    "category": "crm",
    "configured": true,
    "conflict_policy": "merge",
    "created_at": "2026-09-18T10:00:00Z",
    "enabled": true,
    "has_token": true,
    "kind": "hubspot",
    "last_pull_at": "2026-09-19T08:00:04Z",
    "last_run_at": "2026-09-19T08:00:04Z",
    "logo": "/v1/integrations/hubspot/logo.svg",
    "name": "HubSpot CRM",
    "next_pull_at": "2026-09-19T08:30:04Z",
    "order": 2,
    "portal_id": "424242",
    "pull_interval_min": 30,
    "push_interval_min": 0,
    "push_mode": "missing_only",
    "push_on_create": true,
    "scope": "project",
    "vendor": "HubSpot"
  },
  "queued": true
}

GET /v1/integrations/{kind}/template.xml#

Download the PBX template. For yeastar_crm: the custom CRM template XML, pre-filled with this deployment's endpoints and the project's custom fields, to upload under Integrations > CRM > Template Management on the PBX. ?auth=bearer (default) authenticates with the client credentials; ?auth=oauth2 uses the authorization-code flow through the console's consent page.

Paramètres

Réponses

Exemple de requête

curl "https://api.voiceland.ai/v1/integrations/{kind}/template.xml" \
  -H "Authorization: Bearer VL_API_KEY"

GET /v1/secrets#

List secrets. Returns your secrets, metadata only, never the value.

Réponses

Exemple de requête

curl "https://api.voiceland.ai/v1/secrets" \
  -H "Authorization: Bearer VL_API_KEY"

Exemple de réponse

{
  "items": [
    {
      "has_value": true,
      "name": "crm_token"
    }
  ]
}

POST /v1/secrets#

Create a secret. Stores an encrypted credential referenced from actions as ${secret:NAME}. Reads never return the value.

Corps de la requête

application/json

Réponses

Exemple de requête

curl -X POST "https://api.voiceland.ai/v1/secrets" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "CRM bearer",
  "name": "crm_token",
  "value": "sk-live-abc123"
}'

Exemple de réponse

{
  "has_value": true,
  "name": "crm_token"
}

DELETE /v1/secrets/{name}#

Delete a secret. Deletes a secret.

Paramètres

Réponses

Exemple de requête

curl -X DELETE "https://api.voiceland.ai/v1/secrets/{name}" \
  -H "Authorization: Bearer VL_API_KEY"

GET /v1/secrets/{name}#

Get a secret. Returns a secret's metadata. Pass ?reveal=true to also return the plaintext value.

Paramètres

Réponses

Exemple de requête

curl "https://api.voiceland.ai/v1/secrets/{name}" \
  -H "Authorization: Bearer VL_API_KEY"

Exemple de réponse

{
  "has_value": true,
  "name": "crm_token"
}

PUT /v1/secrets/{name}#

Update a secret. Replaces a secret's value/description.

Paramètres

Corps de la requête

application/json

Réponses

Exemple de requête

curl -X PUT "https://api.voiceland.ai/v1/secrets/{name}" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "CRM bearer",
  "name": "crm_token",
  "value": "sk-live-def456"
}'

Exemple de réponse

{
  "has_value": true,
  "name": "crm_token"
}

Schémas#

Action#

A reusable, parameterised HTTP request your agents can call. Placeholders ${var} and ${secret:name} are substituted at run time.

ActionInput#

Endpoints#

Error#

Error envelope returned for non-2xx responses.

ExtractRule#

Flow#

An ordered chain of actions that passes data step to step.

FlowInput#

FlowOutput#

FlowStep#

IntegrationRequest#

IntegrationView#

ProjectIntegrationRequest#

ProjectIntegrationView#