select_address - Clawdot虾点·文档中心

select_address

Materializes an address search suggestion (suggestion_token) together with recipient details into a gateway address, or re-selects an already-saved address (address_id), and returns the gateway address ID address_id for use by search_shops, preview_order, etc.

Address flow: search_addresses → suggestion token → select_address (with token + recipient) → address_id → used by search_shops (location) / preview_order (ordering). The address_id is issued by the gateway and passed back as-is; do not fabricate it.

Two modes (pick one):

Create: pass suggestion_token (the token from search_addresses) + contact_name + contact_phone + address_detail; the gateway registers a new delivery address upstream and persists it.
Re-select: pass an existing address_id to fetch that address back (still send contact_name / contact_phone, but the saved record is not modified).

Sending neither returns PUBLIC_REFERENCE_INVALID.

Parameters

Parameter	Type	Required	Default	Description
`consent_grant_id`	string	Yes	—	User consent grant ID (`cg_` prefix, from `verify_user_bind`), identifying the consenting user
`suggestion_token`	string \| null	No	`null`	Address suggestion token (the `token` returned by `search_addresses`); required when creating a new address
`address_id`	string \| null	No	`null`	Saved gateway address ID (from a previous `select_address`); pass this to re-select a saved address. Mutually exclusive with `suggestion_token`; sending neither is an error
`contact_name`	string	Yes	—	Recipient name, at most 12 characters (counted by characters, CJK or Latin alike; surrounding whitespace is not counted). Longer names return `PUBLIC_REFERENCE_INVALID` with a message naming `contact_name`
`contact_phone`	string	Yes	—	Recipient phone number
`address_detail`	string	No	`""`	Apartment / floor / room number. Must be non-empty when creating a new POI address (upstream rejects blank detail), otherwise returns `DETAIL_REQUIRED`

Returns

Field	Type	Description
`address_id`	string	Gateway address ID (`addr_` prefix, string); pass it as-is to `search_shops`, `preview_order`, etc. Stays the same on re-select
`display_name`	string	Address display name (the POI name chosen in the suggestion)
`address_detail`	string	Apartment / floor / room number
`city`	string	City name (e.g. “武汉”). Older addresses may return an empty string, meaning unknown — not a different city.
`lat`	number \| null	Latitude
`lng`	number \| null	Longitude
`contact_name`	string \| null	Recipient name
`contact_phone_masked`	string	Masked recipient phone (middle four digits masked, e.g. `138**8000`); the full number is never returned. Strictly `string \| null` (empty number → `null`, fewer than 7 digits → `*`), but a saved address always has a phone, so in practice it is always a non-empty masked string

Error Codes

code	Description
`CONSENT_GRANT_REQUIRED`	Missing consent grant (no `consent_grant_id`)
`CONSENT_GRANT_INVALID`	Consent grant is invalid
`CONSENT_GRANT_EXPIRED`	Consent grant has expired; re-authorization required
`CAP_NOT_BOUND`	The delivery capability is not enabled for this agent
`CONSENT_GRANT_WRONG_CAP`	Consent grant belongs to a different capability / provider
`PUBLIC_REFERENCE_INVALID`	`address_id` is invalid / not owned by the consenting user, neither `suggestion_token` nor `address_id` was provided, or a parameter is invalid (e.g. `contact_name` longer than 12 characters)
`SUGGESTION_EXPIRED`	`suggestion_token` is invalid or expired; re-run `search_addresses`
`CONTACT_REQUIRED`	Missing recipient name or phone
`DETAIL_REQUIRED`	Missing non-empty apartment / floor when creating a new POI address
`ADDRESS_CONTACT_NAME_TOO_LONG`	Recipient name exceeds 12 characters and the platform refused to register it (normally caught earlier as `PUBLIC_REFERENCE_INVALID`)
`ADDRESS_CREATE_REJECTED`	The platform refused to register this address (business reason). Retry with a different suggestion
`ELEME_ERROR`	Upstream address registration failed (network / platform fault)

See Error Handling for the full list.

Example Call

{
  "name": "select_address",
  "arguments": {
    "consent_grant_id": "cg_your_consent_grant",
    "suggestion_token": "<token from search_addresses>",
    "contact_name": "Zhang San",
    "contact_phone": "13800138000",
    "address_detail": "Building 3, Room 101"
  }
}