Contact cards

A contact card lets an agent present a name, title, organization and optional photo in one conversation. Keiki sends it as a contact the recipient can save; it does not change the phone line's own contact card.

Turn it on

In the agent form, enable Contact cards in Abilities. It is off by default. You can also enable it through the developer API:

curl -X PATCH -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "<agent-id>", "features": {"contactCards": true}}' \
  https://<your-host>/api/v1/developer/config

Set a card

When enabled, the set_contact_card tool is available in phone-number iMessage conversations. First and last name are required; organization, title, and photo are optional. photo can be "agent_avatar", "none", or a file path in the agent's sandbox when Code is enabled. send defaults to true; set it to false to save the card without sending it yet.

{
  "first_name": "Alex",
  "last_name": "Morgan",
  "organization": "Acme",
  "title": "Support",
  "photo": "agent_avatar"
}

The tool returns a result shaped like:

{
  "success": true,
  "card": {
    "first_name": "Alex",
    "last_name": "Morgan",
    "organization": "Acme",
    "title": "Support",
    "has_photo": true
  },
  "delivered": true
}

Limits and control

Contact cards are supported only in iMessage conversations. A last name is required. Agents can set a card at most three times per conversation in a rolling 24-hour period. A card set by a teammate is locked against agent changes until a teammate clears it. The recipient must save the contact to keep it; clearing a card does not remove a copy already saved.

From the dashboard

Open an iMessage conversation and choose Contact card to set how the agent appears in that thread. Save and send delivers the card; Save without sending saves it for later. Clear the card to resume the line's own card share. A card set by a teammate locks out agent changes until it is cleared.

Teammates can read, set, and clear a card from the dashboard API: GET, PUT, and DELETE /conversations/:phone/contact-card. Include agentId or apiKey in the query when needed to identify the conversation. The PUT body accepts firstName, lastName, optional organization and title, photo (agent_avatar, none, or keep), optional base64 image photoData, and send.

While a dynamic card exists, Keiki pauses the phone line's native daily contact card share for that conversation. Clearing the dynamic card re-enables it.