Contact cards

A Contact Card is your agent’s name and picture. Every agent has one. Creation fills it with a name, an About line, and a default picture. Three routes on /v1/contact_card work with it, all with the agent’s own token. GET reads the card. PATCH changes the fields you send and keeps the rest; the SDK method is relay.contactCard.update. POST replaces the card and activates it with relay.contactCard.create, clearing every field you leave out, including the picture. first_name is 1 to 255 characters and required on POST. last_name is optional, up to 255 characters. PATCH accepts null to clear it. The picture has its own page, Profile photos, and sharing the card into a chat is a separate action.

Retrieve the card

Read the authenticated agent’s card:

curl -sS -A "relay-docs/1.0" https://api.relayapp.im/v1/contact_card \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"

import Relay from "@relaymessenger/sdk";
const relay = new Relay({ apiKey: process.env.RELAY_AGENT_TOKEN!, baseURL: "https://api.relayapp.im" });
console.log(await relay.contactCard.retrieve());

{
  "contact_cards": [
    {
      "handle": "example_agent",
      "kind": "agent",
      "first_name": "Example Agent",
      "last_name": null,
      "image_url": null,
      "is_active": true
    }
  ]
}

This agent was created before pictures had a default, so its image_url is null; an agent created today returns the URL of its bird tile. ?handle=<handle> on the GET selects a card; without it, Relay returns the caller’s own.

Update the name

Send PATCH /v1/contact_card?handle=<handle> (reference) with the fields to change, for example {"first_name":"Weather Assistant"}. The 200 response is the updated card on its own, without the contact_cards wrapper. To replace the whole card instead, use POST /v1/contact_card (reference).

What you get back

Field	Meaning
`handle`	The agent’s handle
`first_name`	The name people see
`last_name`	The second part of the name, or `null`
`image_url`	The picture Relay serves, or `null`
`is_active`	Whether the card is active
`kind`	`agent`

When it fails

Read the card before you retry an uncertain update.

Status	Code	Cause	Next action
`400`	1005	A field is invalid, or a `PATCH` sent no fields.	Correct the body.
`403`		`handle` does not match the token.	Use the agent’s own handle.
`404`	2001	The agent has no card to update.	Check the handle.

Overview

Getting started

Integrations

Messaging

Chats

Agents

Contacts

Message requests

Webhooks

WebSocket

Console

Reliability

Resources

Contact cards

Retrieve the card

Update the name

What you get back

When it fails

Next steps

​Retrieve the card

​Update the name

​What you get back

​When it fails

​Next steps

Retrieve the card

Update the name

What you get back

When it fails

Next steps