Antwoorden via de Apple Messages API

Verstuur een tekstantwoord in een bestaand Apple Messages-gesprek via de openbare Bird API, controleer daarna de verwerkingsstatus en ontvang klantantwoorden.

Bereid de werkruimte en inloggegevens voor

Doorloop de quickstart voor je eerste gesprek in het dashboard om een bedrijf te koppelen en een testgesprek te openen. Een bedrijf met de status Draft kan vóór goedkeuring testberichten versturen. Gewone antwoorden gebruiken de ondoorzichtige Apple-identifier van de klant; een telefoonnummer kan die niet vervangen.

Maak een API-sleutel voor de werkruimte met amb:read, amb:write en amb_management:read. Gebruik Bash met curl, jq en uuidgen. Voer de volgende blokken uit in één Bash-script of shell. De foutinstellingen stoppen de walkthrough als een verzoek of validatie mislukt. Bewaar inloggegevens in je omgeving, niet in bronbestanden:

Codevoorbeeld

set -euo pipefail
read -r -s -p "Bird API key: " BIRD_API_KEY
printf '\n'
export BIRD_API_KEY
case "$BIRD_API_KEY" in
  bk_eu1_*) BIRD_API_URL=https://eu1.platform.bird.com ;;
  bk_us1_*) BIRD_API_URL=https://us1.platform.bird.com ;;
  *) printf 'Use a workspace key for a supported region.\n' >&2; exit 1 ;;
esac

De sleutel levert de werkruimtecontext. Zie regio's als je een regiofout ontvangt.

Selecteer het bedrijf en het gesprek

Toon bedrijven en gesprekken:

Codevoorbeeld

curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/business-accounts" \
  -H "Authorization: Bearer $BIRD_API_KEY" | jq .
curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/conversations" \
  -H "Authorization: Bearer $BIRD_API_KEY" | jq .
read -r -p "Bird business record ID: " BUSINESS_ID
read -r -p "Bird conversation record ID: " CONVERSATION_ID
BUSINESS=$(curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/business-accounts/$BUSINESS_ID" \
  -H "Authorization: Bearer $BIRD_API_KEY")
CONVERSATION=$(curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/conversations/$CONVERSATION_ID" \
  -H "Authorization: Bearer $BIRD_API_KEY")
printf '%s' "$BUSINESS" | jq -e '.status == "pending" or .status == "active"'
printf '%s' "$CONVERSATION" | jq -e --arg business "$BUSINESS_ID" \
  '.status == "open" and .business_account_id == $business'

Dit voorbeeld is voor een geautoriseerd testgesprek; de status Draft geeft geen toestemming voor een publieke lancering. Stop als een van beide controles false retourneert of een verzoek mislukt. Selecteer records van hetzelfde bedrijf. Gebruik cursorpaginering voor meer resultaten; de eerste pagina is niet de volledige inventaris.

Beoordeel en verstuur het antwoord

Bouw het verzoek met apple_business_id als from en opaque_user_id als to:

Codevoorbeeld

APPLE_BUSINESS_ID=$(printf '%s' "$BUSINESS" | jq -er '.apple_business_id')
OPAQUE_USER_ID=$(printf '%s' "$CONVERSATION" | jq -er '.opaque_user_id')
REQUEST=$(jq -n --arg from "$APPLE_BUSINESS_ID" --arg to "$OPAQUE_USER_ID" \
  '{from:$from,to:$to,content:{type:"text",body:"We can help arrange your visit. Which day works for you?"}}')
printf '%s\n' "$REQUEST" | jq .

Controleer het bedrijf, de ontvanger en de tekst. Het volgende verzoek plaatst een echt, mogelijk factureerbaar bericht in de wachtrij:

Codevoorbeeld

REQUEST_ID=$(uuidgen)
RESPONSE=$(curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $REQUEST_ID" \
  --data "$REQUEST")
printf '%s\n' "$RESPONSE" | jq .
MESSAGE_ID=$(printf '%s' "$RESPONSE" | jq -er '.id')

Een 202-antwoord bevestigt acceptatie voor asynchrone verwerking. Bewaar REQUEST_ID en de ongewijzigde body wanneer je dat logische verzoek opnieuw probeert; een nieuwe sleutel genereren kan een extra bericht aanmaken. Zie idempotentie.

Verwerking inspecteren en antwoorden ontvangen

Gebruik Get message en List message events:

Codevoorbeeld

curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $BIRD_API_KEY" | jq .
curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/messages/$MESSAGE_ID/events" \
  -H "Authorization: Bearer $BIRD_API_KEY" | jq .

Configureer voor asynchrone updates webhooks voor amb.accepted, amb.sent, amb.send_failed, amb.rejected, amb.received en de vereiste gesprekscyclus-events. Verifieer handtekeningen, dedupliseer webhook-afleveringen en tolereer events die niet op volgorde binnenkomen. Haal het bericht op wanneer je een onzekere status afstemt.

Inspecteer bij amb.received de inkomende content en koppel het gesprek aan je openstaande klanttaak. Verwerk native antwoorden met de verzonden identifiers waar beschikbaar; een time-picker-antwoord kan een geselecteerd label bevatten. Controleer het boekings-, bestel- of zaaksysteem voordat je een onomkeerbare actie uitvoert of het resultaat ervan bevestigt.

Berichtinhoud uitbreiden

De Send message reference definieert text-, rich_link- en interactive-content. Interactieve berichten omvatten quick replies, lijsten, time pickers, formulieren en aangepaste iMessage-apps. Gebruik de native-message design guidance voor de klantervaring.

Gebruik voor door Apple gegenereerde voorbeelden de ondersteunde linkworkflow in het dashboard. Bron-URL’s voor media worden tijdens de verwerking opgehaald en kunnen na acceptatie mislukken; volg de mediavereisten.

CLI- of MCP-installaties die bird amb of de bijbehorende amb_*-tools beschikbaar stellen, gebruiken dezelfde adresserings- en statussemantiek. Controleer het geïnstalleerde commando- of toolschema voordat je het gebruikt; deze walkthrough is rechtstreeks afhankelijk van de publieke HTTP-specificaties.

Fouten oplossen

Een 404 kan duiden op een onbekend gesprek of de verkeerde werkruimte. Een 403 vereist de scope van de operatie. Een gesloten gesprek of niet-ondersteunde native interactie kan 422 opleveren; de klant moet een gesloten gesprek opnieuw openen. Volg bij 429 Retry-After en de gedeelde richtlijnen voor beperking van het aantal verzoeken.

Inspecteer na acceptatie berichtgebeurtenissen en statussen op een verwerkings- of factureringsfout. Sent is acceptatie door de Apple-gateway; het biedt geen aflever- of leesbevestiging op het apparaat. Meet bedrijfsresultaten afzonderlijk.