Copy page
View as Markdown View this page as plain textOpen in Claude Ask questions about this page
API reference

Provider connections

Provider readiness, Meta onboarding, token rotation, and disconnect for public API integrations.

Credentials are write-only. Responses expose status, readiness, channel metadata, and provider identifiers, but never return plaintext access tokens, webhook secrets, app secrets, or payment receiver credentials.

Readiness

GET/v1/provider-connections/status

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.

Response

FieldTypeNotes
objectrequired"provider_connection_status"
environmentrequired"sandbox" | "production"
channelsrequiredobject

List

GET/v1/provider-connections

Response

FieldTypeNotes
objectrequired"list"
datarequiredobject[]
has_morerequiredboolean
next_cursorrequiredstring | null

Retrieve

GET/v1/provider-connections/{connection_id}

Response

FieldTypeNotes
idrequiredstring
objectrequired"provider_connection"
providerrequired"meta" | "iniciador" | "abacate_pay"
channelrequired"whatsapp" | "instagram" | "payments" | "agentic_payments"
statusrequired"pending" | "connected" | "suspended" | "disconnected"
display_namerequiredstring
environmentrequired"sandbox" | "production"
waba_idrequiredstring | null
phone_number_idrequiredstring | null
display_phone_numberstring | null
ig_business_account_idrequiredstring | null
page_idrequiredstring | null
provider_account_idrequiredstring | null
payment_receiverrequiredobject | null
payment_capabilitiesrequiredobject | null
agentic_capabilitiesrequiredobject | null
default_participant_idrequiredstring | null
agent_idrequiredstring | null
agentic_api_base_urlrequiredstring | null
webhook_secret_configuredrequiredboolean
suspension_reasonstring | null
last_policy_warning_typestring | null
last_policy_warning_atstring<ISO-8601> | null
send_capability"available" | "blocked" | null
Latest trusted Meta WABA send capability. Null means no trusted observation yet; it never changes the connection lifecycle status.
send_block_codes"141006" | "141008" | "141011"[] | null
Recognized Meta send-block diagnostics, ordered for remediation: 141006 payment, 141008 inactive WABA, then 141011 messaging permission.
send_capability_observed_atstring<ISO-8601> | null
ISO-8601 timestamp of the trusted Meta WABA capability observation.
waba_send_capabilitiesobject[]
WABA-keyed capability evidence observed through this connection. Includes the primary WABA when known; private refresh-attempt timestamps are omitted.
waba_ban_datestring<ISO-8601> | null
waba_ban_statestring | null
account_review_statusstring | null
restrictionsobject[] | null
credential_last_fourstring | null
token_sourcerequired"manual" | "embedded_signup" | null
token_expires_atrequiredstring<ISO-8601> | null
token_refreshed_atrequiredstring<ISO-8601> | null
token_rotated_atrequiredstring<ISO-8601> | null
created_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
updated_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
disconnected_atrequiredstring<ISO-8601> | null

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_idfor 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_errorfor 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

POST/v1/provider-credential-setup-sessions201 Created - Idempotency-Key supported

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: "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

FieldTypeNotes
targetrequired"meta.whatsapp" | "abacate_pay.payments" | "iniciador.payments" | "iniciador.agentic_payments" | "openai.tts" | "elevenlabs.tts" | "xai.tts" | "openai.stt"

Response

FieldTypeNotes
No fields.
GET/v1/provider-credential-setup-sessions/{request_id}

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

FieldTypeNotes
No fields.

Hosted Meta signup session

POST/v1/meta-signup-sessions201 Created - Idempotency-Key required

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

FieldTypeNotes
return_urlrequiredstring
len 0..2048
end_customer_refstring
len 1..200

Response

FieldTypeNotes
idrequiredstring
pattern: ^mss_.*
objectrequired"meta_signup_session"
statusrequired"pending" | "processing" | "completed" | "expired"
urlrequiredstring | null
return_urlrequiredstring
end_customer_refrequiredstring | null
project_idrequiredstring
environment_idrequiredstring
environmentrequired"sandbox" | "production"
expires_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
completed_atrequiredstring<ISO-8601> | null
provider_connection_idrequiredstring | null
created_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
updated_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
GET/v1/meta-signup-sessions/{session_id}

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

FieldTypeNotes
idrequiredstring
pattern: ^mss_.*
objectrequired"meta_signup_session"
statusrequired"pending" | "processing" | "completed" | "expired"
urlrequiredstring | null
return_urlrequiredstring
end_customer_refrequiredstring | null
project_idrequiredstring
environment_idrequiredstring
environmentrequired"sandbox" | "production"
expires_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
completed_atrequiredstring<ISO-8601> | null
provider_connection_idrequiredstring | null
created_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
updated_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Meta onboarding config

GET/v1/provider-connections/meta/onboarding

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

FieldTypeNotes
objectrequired"meta_onboarding_config"
moderequired"embedded_signup"
app_idrequiredstring
len 1..∞
config_idrequiredstring
len 1..∞
graph_api_versionrequiredstring
len 1..∞
sdk_urlrequiredstring
allowed_message_originsrequiredstring[]
message_typerequired"WA_EMBEDDED_SIGNUP"
login_optionsrequiredobject
completion_endpointrequired"/v1/provider-connections/meta/oauth"
manual_credentials_endpointrequired"/v1/provider-connections/meta"

Register Meta connection

POST/v1/provider-connections/meta201 Created - Idempotency-Key supported

The access_tokenmust 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 (400, param: "access_token") whenever Meta's rejection is specific enough to recognize; shapes Meta reports differently still answer 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

FieldTypeNotes
channel"whatsapp" | "instagram" | "payments" | "agentic_payments"
display_namerequiredstring
len 1..∞
waba_idstring
len 1..∞
phone_number_idstring
len 1..∞
ig_business_account_idstring
len 1..∞
page_idstring
len 1..∞
access_tokenrequiredstring
len 1..∞
token_source"manual" | "embedded_signup"
token_expires_atstring<ISO-8601> | null

Response

FieldTypeNotes
idrequiredstring
objectrequired"provider_connection"
providerrequired"meta" | "iniciador" | "abacate_pay"
channelrequired"whatsapp" | "instagram" | "payments" | "agentic_payments"
statusrequired"pending" | "connected" | "suspended" | "disconnected"
display_namerequiredstring
environmentrequired"sandbox" | "production"
waba_idrequiredstring | null
phone_number_idrequiredstring | null
display_phone_numberstring | null
ig_business_account_idrequiredstring | null
page_idrequiredstring | null
provider_account_idrequiredstring | null
payment_receiverrequiredobject | null
payment_capabilitiesrequiredobject | null
agentic_capabilitiesrequiredobject | null
default_participant_idrequiredstring | null
agent_idrequiredstring | null
agentic_api_base_urlrequiredstring | null
webhook_secret_configuredrequiredboolean
suspension_reasonstring | null
last_policy_warning_typestring | null
last_policy_warning_atstring<ISO-8601> | null
send_capability"available" | "blocked" | null
Latest trusted Meta WABA send capability. Null means no trusted observation yet; it never changes the connection lifecycle status.
send_block_codes"141006" | "141008" | "141011"[] | null
Recognized Meta send-block diagnostics, ordered for remediation: 141006 payment, 141008 inactive WABA, then 141011 messaging permission.
send_capability_observed_atstring<ISO-8601> | null
ISO-8601 timestamp of the trusted Meta WABA capability observation.
waba_send_capabilitiesobject[]
WABA-keyed capability evidence observed through this connection. Includes the primary WABA when known; private refresh-attempt timestamps are omitted.
waba_ban_datestring<ISO-8601> | null
waba_ban_statestring | null
account_review_statusstring | null
restrictionsobject[] | null
credential_last_fourstring | null
token_sourcerequired"manual" | "embedded_signup" | null
token_expires_atrequiredstring<ISO-8601> | null
token_refreshed_atrequiredstring<ISO-8601> | null
token_rotated_atrequiredstring<ISO-8601> | null
created_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
updated_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
disconnected_atrequiredstring<ISO-8601> | null

Exchange Meta OAuth code

POST/v1/provider-connections/meta/oauth201 Created - Idempotency-Key supported

Send waba_idwhen 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 it returns meta_waba_missing (400, param: "waba_id") and keeps a retryable pending setup; no candidate account IDs are returned.

Request body

FieldTypeNotes
coderequiredstring
len 1..∞
waba_idstring
len 1..∞
phone_number_idstring
len 1..∞
display_namestring
len 1..∞
business_idstring
len 1..∞
signup_session_idstring
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Response

FieldTypeNotes
idrequiredstring
objectrequired"provider_connection"
providerrequired"meta" | "iniciador" | "abacate_pay"
channelrequired"whatsapp" | "instagram" | "payments" | "agentic_payments"
statusrequired"pending" | "connected" | "suspended" | "disconnected"
display_namerequiredstring
environmentrequired"sandbox" | "production"
waba_idrequiredstring | null
phone_number_idrequiredstring | null
display_phone_numberstring | null
ig_business_account_idrequiredstring | null
page_idrequiredstring | null
provider_account_idrequiredstring | null
payment_receiverrequiredobject | null
payment_capabilitiesrequiredobject | null
agentic_capabilitiesrequiredobject | null
default_participant_idrequiredstring | null
agent_idrequiredstring | null
agentic_api_base_urlrequiredstring | null
webhook_secret_configuredrequiredboolean
suspension_reasonstring | null
last_policy_warning_typestring | null
last_policy_warning_atstring<ISO-8601> | null
send_capability"available" | "blocked" | null
Latest trusted Meta WABA send capability. Null means no trusted observation yet; it never changes the connection lifecycle status.
send_block_codes"141006" | "141008" | "141011"[] | null
Recognized Meta send-block diagnostics, ordered for remediation: 141006 payment, 141008 inactive WABA, then 141011 messaging permission.
send_capability_observed_atstring<ISO-8601> | null
ISO-8601 timestamp of the trusted Meta WABA capability observation.
waba_send_capabilitiesobject[]
WABA-keyed capability evidence observed through this connection. Includes the primary WABA when known; private refresh-attempt timestamps are omitted.
waba_ban_datestring<ISO-8601> | null
waba_ban_statestring | null
account_review_statusstring | null
restrictionsobject[] | null
credential_last_fourstring | null
token_sourcerequired"manual" | "embedded_signup" | null
token_expires_atrequiredstring<ISO-8601> | null
token_refreshed_atrequiredstring<ISO-8601> | null
token_rotated_atrequiredstring<ISO-8601> | null
created_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
updated_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
disconnected_atrequiredstring<ISO-8601> | null

Complete a pending Meta registration

POST/v1/provider-connections/{connection_id}/meta/complete-registrationIdempotency-Key supported - no request body

Finishes a Meta WhatsApp connection that reads status: "pending" because signup stopped after the access token was already brokered. If the original relay had no WABA, the retry proves one from the stored token before the remaining provider steps re-run; the credentials are revalidated, and the connection comes back connected - without running WhatsApp signup in a browser again. If it fails, the connection stays pending and can be retried once the underlying cause (for example a missing payment method on the WhatsApp Business Account) is fixed.

Response

FieldTypeNotes
idrequiredstring
objectrequired"provider_connection"
providerrequired"meta" | "iniciador" | "abacate_pay"
channelrequired"whatsapp" | "instagram" | "payments" | "agentic_payments"
statusrequired"pending" | "connected" | "suspended" | "disconnected"
display_namerequiredstring
environmentrequired"sandbox" | "production"
waba_idrequiredstring | null
phone_number_idrequiredstring | null
display_phone_numberstring | null
ig_business_account_idrequiredstring | null
page_idrequiredstring | null
provider_account_idrequiredstring | null
payment_receiverrequiredobject | null
payment_capabilitiesrequiredobject | null
agentic_capabilitiesrequiredobject | null
default_participant_idrequiredstring | null
agent_idrequiredstring | null
agentic_api_base_urlrequiredstring | null
webhook_secret_configuredrequiredboolean
suspension_reasonstring | null
last_policy_warning_typestring | null
last_policy_warning_atstring<ISO-8601> | null
send_capability"available" | "blocked" | null
Latest trusted Meta WABA send capability. Null means no trusted observation yet; it never changes the connection lifecycle status.
send_block_codes"141006" | "141008" | "141011"[] | null
Recognized Meta send-block diagnostics, ordered for remediation: 141006 payment, 141008 inactive WABA, then 141011 messaging permission.
send_capability_observed_atstring<ISO-8601> | null
ISO-8601 timestamp of the trusted Meta WABA capability observation.
waba_send_capabilitiesobject[]
WABA-keyed capability evidence observed through this connection. Includes the primary WABA when known; private refresh-attempt timestamps are omitted.
waba_ban_datestring<ISO-8601> | null
waba_ban_statestring | null
account_review_statusstring | null
restrictionsobject[] | null
credential_last_fourstring | null
token_sourcerequired"manual" | "embedded_signup" | null
token_expires_atrequiredstring<ISO-8601> | null
token_refreshed_atrequiredstring<ISO-8601> | null
token_rotated_atrequiredstring<ISO-8601> | null
created_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
updated_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
disconnected_atrequiredstring<ISO-8601> | null

Rotate token

POST/v1/provider-connections/{connection_id}/rotateIdempotency-Key supported

Validates the replacement access token against Meta and stores it encrypted; the plaintext token is never returned. 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 (400, param: "access_token") whenever Meta's rejection is specific enough to recognize; shapes Meta reports differently still answer whatsapp_credentials_invalid (or instagram_credentials_invalid). The constraint itself does not depend on which answer you get, and the same rule applies when registering a connection. A token that is simply invalid or expired also returns 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

FieldTypeNotes
access_tokenrequiredstring
len 1..∞
token_source"manual" | "embedded_signup"
token_expires_atstring<ISO-8601> | null

Response

FieldTypeNotes
idrequiredstring
objectrequired"provider_connection"
providerrequired"meta" | "iniciador" | "abacate_pay"
channelrequired"whatsapp" | "instagram" | "payments" | "agentic_payments"
statusrequired"pending" | "connected" | "suspended" | "disconnected"
display_namerequiredstring
environmentrequired"sandbox" | "production"
waba_idrequiredstring | null
phone_number_idrequiredstring | null
display_phone_numberstring | null
ig_business_account_idrequiredstring | null
page_idrequiredstring | null
provider_account_idrequiredstring | null
payment_receiverrequiredobject | null
payment_capabilitiesrequiredobject | null
agentic_capabilitiesrequiredobject | null
default_participant_idrequiredstring | null
agent_idrequiredstring | null
agentic_api_base_urlrequiredstring | null
webhook_secret_configuredrequiredboolean
suspension_reasonstring | null
last_policy_warning_typestring | null
last_policy_warning_atstring<ISO-8601> | null
send_capability"available" | "blocked" | null
Latest trusted Meta WABA send capability. Null means no trusted observation yet; it never changes the connection lifecycle status.
send_block_codes"141006" | "141008" | "141011"[] | null
Recognized Meta send-block diagnostics, ordered for remediation: 141006 payment, 141008 inactive WABA, then 141011 messaging permission.
send_capability_observed_atstring<ISO-8601> | null
ISO-8601 timestamp of the trusted Meta WABA capability observation.
waba_send_capabilitiesobject[]
WABA-keyed capability evidence observed through this connection. Includes the primary WABA when known; private refresh-attempt timestamps are omitted.
waba_ban_datestring<ISO-8601> | null
waba_ban_statestring | null
account_review_statusstring | null
restrictionsobject[] | null
credential_last_fourstring | null
token_sourcerequired"manual" | "embedded_signup" | null
token_expires_atrequiredstring<ISO-8601> | null
token_refreshed_atrequiredstring<ISO-8601> | null
token_rotated_atrequiredstring<ISO-8601> | null
created_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
updated_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
disconnected_atrequiredstring<ISO-8601> | null

Disconnect

DELETE/v1/provider-connections/{connection_id}

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

Response

FieldTypeNotes
idrequiredstring
objectrequired"provider_connection"
providerrequired"meta" | "iniciador" | "abacate_pay"
channelrequired"whatsapp" | "instagram" | "payments" | "agentic_payments"
statusrequired"pending" | "connected" | "suspended" | "disconnected"
display_namerequiredstring
environmentrequired"sandbox" | "production"
waba_idrequiredstring | null
phone_number_idrequiredstring | null
display_phone_numberstring | null
ig_business_account_idrequiredstring | null
page_idrequiredstring | null
provider_account_idrequiredstring | null
payment_receiverrequiredobject | null
payment_capabilitiesrequiredobject | null
agentic_capabilitiesrequiredobject | null
default_participant_idrequiredstring | null
agent_idrequiredstring | null
agentic_api_base_urlrequiredstring | null
webhook_secret_configuredrequiredboolean
suspension_reasonstring | null
last_policy_warning_typestring | null
last_policy_warning_atstring<ISO-8601> | null
send_capability"available" | "blocked" | null
Latest trusted Meta WABA send capability. Null means no trusted observation yet; it never changes the connection lifecycle status.
send_block_codes"141006" | "141008" | "141011"[] | null
Recognized Meta send-block diagnostics, ordered for remediation: 141006 payment, 141008 inactive WABA, then 141011 messaging permission.
send_capability_observed_atstring<ISO-8601> | null
ISO-8601 timestamp of the trusted Meta WABA capability observation.
waba_send_capabilitiesobject[]
WABA-keyed capability evidence observed through this connection. Includes the primary WABA when known; private refresh-attempt timestamps are omitted.
waba_ban_datestring<ISO-8601> | null
waba_ban_statestring | null
account_review_statusstring | null
restrictionsobject[] | null
credential_last_fourstring | null
token_sourcerequired"manual" | "embedded_signup" | null
token_expires_atrequiredstring<ISO-8601> | null
token_refreshed_atrequiredstring<ISO-8601> | null
token_rotated_atrequiredstring<ISO-8601> | null
created_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
updated_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
disconnected_atrequiredstring<ISO-8601> | null