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
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
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 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 required

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
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
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 required

Request body

FieldTypeNotes
coderequiredstring
len 1..∞
waba_idrequiredstring
len 1..∞
phone_number_idrequiredstring
len 1..∞
display_namestring
len 1..∞
business_idstring
len 1..∞

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
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
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 required

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