Provider connections

Readiness

Requires provider_connections:read. Use this as the first integration check: one response answers whether WhatsApp, Instagram, merchant payments, or agentic payments are ready for the API key environment.

channels.agentic_payments.platform_default reports whether Tyxter’s managed connection is configured, whether a managed row exists, and its KYC eligibility. A missing or disconnected connection is provisioned on first agentic use when eligible; connected customer credentials keep precedence. Availability alone does not set ready.

Response

List

Response

Retrieve

Response

Meta WABA send capability

Meta WhatsApp responses include optional, nullable compatibility fields for the connection's primary WABA: send_capability, send_block_codes, and send_capability_observed_at. The optional waba_send_capabilities array carries the same evidence keyed by waba_id for sender WABAs observed through the connection. Use the entry matching the sending phone's WABA; one token can legitimately reach more than one WABA. A null capability or missing entry means Tyxter has no trusted observation yet, not that sending is available. When Meta reports a block, codes are ordered for remediation: 141006 (add a payment method in WhatsApp Manager → Billing & payments), 141008 (reactivate the WABA in WhatsApp Manager or ask Meta support), then 141011 (reconnect and grant the requested WhatsApp messaging permissions, then ask support if it persists). All recognized codes remain in the array for diagnosis.

This is delivery evidence, not a connection or phone-number lifecycle state: a blocked capability leaves status: "connected" intact and inbound messages available. A fresh stored block can terminate a queued send before any Meta call, so that receipt has a stable error_code and provider_error: null. When a Meta send failure triggers a reactive health confirmation that proves a block, the same terminal receipt preserves the original bounded Meta provider_error for diagnosis. After the account is fixed, Tyxter can observe a positive available result and clear that WABA's capability evidence; private per-WABA check-attempt times are never returned. See delivery errors for the stable failed-message codes and retry posture.

Provider credential setup session

Creates a short-lived browser handoff so a human owner or admin can enter provider credentials without exposing secrets to the calling agent. Use target: "salvy" for Salvy BYOK: the returned setup_url opens Connections → Providers, where an owner or admin enters the Salvy key and accepts the BYOK terms. Salvy validation runs asynchronously; the hosted flow completes this setup session only after the connection is connected, and the poll response then includes completed_provider_connection_id. If completion arrives before the connection is configured, provider_credential_setup_target_not_configured (409) leaves the session pending so the dashboard can retry. Use target: "abacate_pay.payments" when merchant-payment workflows need a payment connection before calling POST /v1/payments. Use target: "openai.stt" when a production environment needs its own OpenAI transcription key. For an integrating agent, this target is the browser handoff to a signed-in human; signed-in dashboard owners and admins can instead use Connections → Speech-to-Text directly. The media guide covers that dashboard path and its validation, pricing, and fallback behavior. Sandbox transcription is deterministic and rejects that target with provider_credential_setup_stt_sandbox_unsupported (400, param: "target") because it needs no provider key or setup session. During a safe two-phase BYOK rollout, the STT target can temporarily return transcription_byok_runtime_inactive (503) before validation or persistence. Retry the same request and Idempotency-Key after activation; no setup session or provider call was created by the rejected request.

Request body

Response

Variant 1

Variant 2

Variant 3

Variant 4

Variant 5

Variant 6

Polls the setup handoff. Retry the payment or provider-dependent workflow only after the session returns status: "completed". Pending, denied, and expired sessions have every completion field set to null. A completed session populates only the field for its target: an STT handoff reports completed_stt_provider: "openai" while the provider-connection and TTS fields remain null. It never returns the key.

Response

Variant 1

Variant 2

Variant 3

Variant 4

Variant 5

Variant 6

Hosted Meta signup session

Creates a 30-minute, Tyxter-hosted Embedded Signup URL for your own product. Open the URL in a popup or new tab; your end user completes Meta signup without receiving Tyxter dashboard access or your API key. The production environment must not already have a live Meta WhatsApp connection, and return_url must use an allowlisted origin.

Request body

Response

Polls pending, processing, completed, or expired. The launch URL is one-time material: create and idempotent replay return it; this polling route returns url: null.

Response

Meta onboarding config

Returns non-secret Facebook SDK launch metadata for Meta Embedded Signup. This route does not return the Meta app secret or a raw OAuth URL.

Response

Register Meta connection

The request never calls Meta. Tyxter seals the credential and returns the connection with its operation (kind: "meta_registration", state: "queued"); a worker then checks the credential with Meta. A new connection is pending until then, and re-registering a connected one keeps it connected on its current token. Poll GET /v1/provider-connections/{connection_id} until operation.state is succeeded (the connection is connected) or failed; operation.error_code is the code this route used to answer synchronously, and meta_validation_failed also marks a registration not finished within fifteen minutes. operation.kind becomes meta_token_rotation, meta_oauth_exchange or meta_registration_completion when a token rotation, an OAuth code exchange (including a hosted Embedded Signup completion's) or a complete-registration queued meanwhile replaced it. Refusals that need no Meta check (a sandbox environment, a policy-suspended account, a phone connected elsewhere) still answer synchronously. Reusing an Idempotency-Key returns the stored 202 body.

The access_token must be one Tyxter's own Meta app minted; a token from your own Meta app is rejected even when it is valid there. Tyxter identifies that case as meta_token_foreign_app on the failed operation whenever Meta's rejection is specific enough to recognize; shapes Meta reports differently still fail with whatsapp_credentials_invalid. The Rotate token section below explains why, and which flow to use when you do not hold a token at all.

Request body

Response

Register a Salvy BYOK connection

Requires an active eligible paid Salvy BYOK plan and the runtime capability. Send the customer's Salvy API key with continuation_terms_version: "salvy_byok_v1". Tyxter seals the key and returns a pending connection; validation and the first number discovery run asynchronously in the provider worker. The API request never calls Salvy, and neither the response nor its idempotency record contains the plaintext key. A 202 means the operation was queued; poll the connection until it reports succeeded, then read the cached numbers route.

Request body

Response

Salvy credential rotation

Queues a generation-fenced replacement key. The current key is retained while the worker validates the candidate and proves that every currently managed provider number is still visible to it; a key is considered validated only after its connection reaches connected. Invalid credentials, provider transport failures, and a number missing from the candidate account discard the candidate and preserve the retained key.

Request body

Response

Salvy discovery refresh

Queues a refresh using the current stored key on a connected connection. Send an empty JSON object. Until the worker succeeds, reads continue to return the last successful snapshot; the API does not call Salvy during this request.

Request body

Response

List cached Salvy numbers

Requires provider_connections:read. Returns cursor-paginated data from the scoped, persisted discovery snapshot. Before the first successful discovery it returns an empty list. This route never decrypts a credential or calls Salvy. imported_phone_number_id is a reserved nullable field and is currently null in this response surface.

Response

Exchange Meta OAuth code

The request never calls Meta. Tyxter seals the single-use code and returns the connection with its operation (kind: "meta_oauth_exchange", state: "queued"); a worker sends the code to Meta at most once, never twice, completes Embedded Signup and registers the connection. Posting the same code again while its exchange is queued returns that exchange’s connection and queues nothing; a different code replaces it. Poll GET /v1/provider-connections/{connection_id} until operation.state is succeeded (the connection is connected) or failed; operation.error_code is the code this route used to answer synchronously. meta_oauth_exchange_failed means Meta rejected the code, and meta_oauth_exchange_unavailable means the exchange could not be completed, including one not finished within fifteen minutes; the code is single-use, so both need a new signup. Refusals that need no Meta call (a sandbox environment, a policy-suspended account, an ended signup run) still answer synchronously. Reusing an Idempotency-Key returns the stored 202 body. The 202 carries display-name warnings only for a display_name the request supplied; the WhatsApp Business Account name the worker reads from Meta later gets none on this route.

Send waba_id when Meta supplied it. If a valid OAuth code arrives without it, Tyxter continues only when the token’s WhatsApp granular scopes prove exactly one account. Otherwise the operation fails with meta_waba_missing and the connection keeps a retryable pending setup; no candidate account IDs are returned.

Request body

Response

Complete a pending Meta registration

Finishes a Meta WhatsApp connection that reads status: "pending" because signup stopped after the access token was already brokered - without running WhatsApp signup in a browser again. Answers 202 without calling Meta: the connection, still pending, comes back with its operation (kind: "meta_registration_completion", state: "queued"). A worker then proves a WABA from the stored token when the original relay had none, re-runs the remaining provider steps and revalidates the credentials. Poll GET /v1/provider-connections/{connection_id} until operation.state is succeeded (the connection is connected) or failed; operation.error_code is the code this route used to answer synchronously, and meta_validation_failed also marks a completion not finished within fifteen minutes. A failed completion leaves the connection pending with its stored credentials, so it can be retried once the underlying cause (for example a missing payment method on the WhatsApp Business Account) is fixed. operation.kind changes when a newer registration, OAuth code exchange or token rotation replaced the queued completion, and sending this request again while one is queued returns that one. A connection that is not Meta WhatsApp, a sandbox environment, an already connected connection, a missing or unreadable stored credential (invalid_provider_connection_request), a policy-suspended account and a deployment without Meta app credentials still answer synchronously. Reusing an Idempotency-Key returns the stored 202 body.

Response

Rotate token

Answers 202 without calling Meta. Tyxter seals the replacement token and returns the connection, still on its current token and status, with its operation (kind: "meta_token_rotation", state: "queued"); the plaintext token is never returned. A worker then validates the token with Meta against the WhatsApp Business Account and phone already on the connection and swaps it in. Poll GET /v1/provider-connections/{connection_id} until operation.state is succeeded (the new token is stored) or failed; a failed rotation keeps the current token, its operation.error_code is one of the stable codes the operation schema enumerates, and meta_validation_failed also marks a rotation not finished within fifteen minutes. operation becomes null when a later credential write replaced the queued rotation, and names meta_registration, meta_oauth_exchange or meta_registration_completion when a later registration, OAuth code exchange or complete-registration replaced it. A disconnected connection, a policy-suspended account, remembered identity enforcement, a deployment without Meta app credentials and a connection missing the identifiers its channel is validated against (invalid_provider_connection_request) still answer synchronously. Reusing an Idempotency-Key returns the stored 202 body.

The replacement must be a token Tyxter's own Meta app minted. A token you created in your own Meta app is always rejected, even when it works in your app, because Tyxter verifies it with its own app credentials, receives your inbound messages on its own app webhook subscription, and refreshes credentials under that same app identity - none of which a token from another app can reach. Tyxter identifies that case as meta_token_foreign_app on the failed operation whenever Meta's rejection is specific enough to recognize; shapes Meta reports differently still fail with whatsapp_credentials_invalid (or instagram_credentials_invalid). The constraint itself does not depend on which code you get, and the same rule applies when registering a connection. A token that is simply invalid or expired also fails with whatsapp_credentials_invalid.

Use this route only when you already hold such a token. The signup flows never hand one back - they complete the connection server-side, and no response returns provider credentials. To replace a credential you do not hold, re-run Meta sign-in from the dashboard connection card or call POST /v1/provider-connections/meta/oauth with a fresh code; either one replaces the stored credential on the existing connection. Hosted signup sessions onboard a customer who has no connection yet, so they are not the rotation path.

Request body

Response

Disconnect

Clears provider credentials without deleting audit history. The connection disappears from list/retrieve and readiness reports it as disconnected or missing.

Response