Request conversation authentication
/v1/amb/conversations/{conversation_id}/authenticationscurl -X POST "https://us1.platform.bird.com/v1/amb/conversations/{conversation_id}/authentications" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"template": {
"slug": "account_sign_in",
"language": "fr"
}
}'{
"id": "amauth_01krdgeqcxet5s7t44vh8rt9mg",
"conversation_id": "acv_01krdgeqcxet5s7t44vh8rt9mg",
"provider_id": "aauthp_01krdgeqcxet5s7t44vh8rt9mg",
"message_id": "amb_01krdgeqcxet5s7t44vh8rt9mg",
"status": "pending"
}
Sends a native sign-in request to an open conversation whose device advertises AUTH2. The business needs an enabled authentication provider. The request expires after ten minutes. Bird validates the provider's response and waits for confirmation from the originating Messages device before storing the verified identity with the conversation. The customer's tokens are never stored or returned. A new request supersedes an unfinished one in the same conversation, including when the new request then fails to send. Reusing an idempotency key returns the original request. The outcome arrives as a webhook event. Read the request to recover a missing event. The request sends the business's sign-in message, or Bird's built-in message when the business has none. Name a template to send another sign-in message template. Bird renders the message when it accepts the request, so a later template change does not alter it.
Parameters
conversation_idstringConversation identifier. Starts with acv_.
Request Payload
templateThe sign-in message template to send in place of the business's sign-in message. The template must be a published sign-in message.
Show child parameters
template.idThe workspace or built-in sign-in message template to send, by ID.
template.languageWhich of the template's languages to send. When the template does not have the language you ask for, its on_missing_language setting decides whether the closest available language is sent instead or the request is rejected. Omit it to send the first of these the template has: the conversation's locale, the business's default locale, then the template's default language. A request that omits it is never rejected for its language, and language_source_required does not apply.
template.parametersValues for the template's variables, keyed by variable name. Read the live version to see the accepted keys and formats. A missing required key, an undeclared key, an invalid value, or a serialized object over 16 KiB returns 422.
template.slugThe workspace or built-in sign-in message template to send, by its immutable slug. Read the template's live version to see its variables.
template.languageWhich of the template's languages to send. When the template does not have the language you ask for, its on_missing_language setting decides whether the closest available language is sent instead or the request is rejected. Omit it to send the first of these the template has: the conversation's locale, the business's default locale, then the template's default language. A request that omits it is never rejected for its language, and language_source_required does not apply.
template.parametersValues for the template's variables, keyed by variable name. Read the live version to see the accepted keys and formats. A missing required key, an undeclared key, an invalid value, or a serialized object over 16 KiB returns 422.
Response Payload
idconversation_idprovider_idprovider_revisionProvider revision used by this attempt.
message_idAuthentication message reference, or null before acceptance.
statusProgress of an authentication request. Every value except pending and processing is terminal.
pending: the sign-in message was accepted and the customer has not finished.processing: the authorization code is being exchanged or Bird is waiting for confirmation from the originating Messages device.succeeded: the identity was validated and the originating Messages device confirmed sign-in.failed: delivery, identity verification or device confirmation failed, or the provider callback was replayed.cancelled: the customer or the provider declined authorization.expired: the request passed its ten-minute lifetime.superseded: a newer request, or a change to the conversation, business or provider, replaced the request.
Possible values: pending, processing, succeeded, failed, cancelled, expired, superseded
created_atWhen the attempt was created.
expires_atWhen this attempt expires.
completed_atWhen the attempt reached a terminal outcome.
failure_codeWhy the request did not succeed. Contains no provider response or credentials.
authentication_expired: ten minutes passed. Request a new sign-in.new_authentication: a newer request replaced this one.conversation_closedandconversation_changed: the conversation closed or reopened. Wait for the customer to write again.configuration_changed: the provider settings changed or the business was disconnected.user_cancelled,apple_authentication_cancel: the customer declined.provider_rejected,token_exchange_failed,identity_verification_failed: the provider response could not be accepted. Check the provider settings, then request a new sign-in.processing_interrupted: the exchange or device confirmation did not finish within one minute. Ask the customer to sign in again and return to Messages.apple_authentication_failure: the Messages device reported a failed sign-in. Request a new sign-in.authentication_replayed: the provider callback was used more than once. Request a new sign-in.message_submission_failed,message_failed: the sign-in message could not be sent.
Other values are message delivery reasons passed through unchanged.
identityValidated identity claims. Verification does not create a persistent login session or grant access to customer systems.
Related resources
Continue with the documentation, guides and examples for this topic.