Send a contact card

Auth. HMAC v1 or bearer token — see Authentication. Status. Live · Idempotent: No.

Builds a vCard from the supplied fields and sends it as a tappable contact bubble in the chat. The recipient sees a normal contact card they can tap to save. Works in both DMs and groups. Wrap the card details in a top-level contact object (or supply raw vcard_text). Include at least one identifying field inside contact — full_name, given_name, family_name, organization, or a non-empty phones / emails. This is independent of the line’s own saved contact card — use share-contact-info to share the line’s “Me” card.

Addressing the recipient

Pick the form that matches your state:

By chat id — POST /api/v1/chats/{id}/send-contact once a chat exists.
By phone — pass to in the request body. Use this on first-touch when no chat exists yet; Chert resolves or creates the chat in-line.

{
  "to": "+14155551234",                  // <- E.164 phone (alternative to {id} in the URL)
  "contact": {
    "full_name": "Sean Franklin",
    "given_name": "Sean",
    "family_name": "Franklin",
    "organization": "Acme Inc",
    "phones": [{ "value": "+14155551234", "label": "mobile" }],
    "emails": [{ "value": "sean@acme.example", "label": "work" }]
  }
}

Request

POST /api/v1/chats/{id}/send-contact

curl -X POST https://console.trychert.com/api/v1/chats/ch_01H.../send-contact \
  -H "x-chert-tenant: $TENANT" \
  -H "x-chert-signature: v1,$TS,$SIG" \
  -H "content-type: application/json" \
  -d '{
    "contact": {
      "full_name": "Sean Franklin",
      "given_name": "Sean",
      "family_name": "Franklin",
      "organization": "Acme Inc",
      "phones": [{ "value": "+14155551234", "label": "mobile" }],
      "emails": [{ "value": "sean@acme.example", "label": "work" }]
    }
  }'

const ts = Math.floor(Date.now() / 1000)
const body = JSON.stringify({
  contact: {
    full_name: "Sean Franklin",
    given_name: "Sean",
    family_name: "Franklin",
    organization: "Acme Inc",
    phones: [{ value: "+14155551234", label: "mobile" }],
    emails: [{ value: "sean@acme.example", label: "work" }],
  },
})
const sig = crypto.createHmac("sha256", SIGNING_SECRET).update(`${ts}.${body}`).digest("hex")
const res = await fetch(
  `https://console.trychert.com/api/v1/chats/${chatId}/send-contact`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-chert-tenant": TENANT_SLUG,
      "x-chert-signature": `v1,${ts},${sig}`,
    },
    body,
  },
)

import hmac, hashlib, json, time, requests
ts = int(time.time())
body = json.dumps({
    "contact": {
        "full_name": "Sean Franklin",
        "given_name": "Sean",
        "family_name": "Franklin",
        "organization": "Acme Inc",
        "phones": [{"value": "+14155551234", "label": "mobile"}],
        "emails": [{"value": "sean@acme.example", "label": "work"}],
    },
})
sig = hmac.new(SIGNING_SECRET.encode(), f"{ts}.{body}".encode(), hashlib.sha256).hexdigest()
r = requests.post(
    f"https://console.trychert.com/api/v1/chats/{chat_id}/send-contact",
    headers={
        "Content-Type": "application/json",
        "x-chert-tenant": TENANT_SLUG,
        "x-chert-signature": f"v1,{ts},{sig}",
    },
    data=body,
)

Response

{
  "chat_id": "ch_01H...",
  "status": "sent"
}

Path parameters

string

Chat identifier (ch_…). Omit and use body.to for first-touch recipients with no chat yet.

Body

Provide either a contact object (canonical) or a raw vcard_text string.

string

Recipient phone in E.164 format. Use instead of the {id} path segment when no chat exists yet. Ignored when {id} is supplied.

object

Canonical contact wrap. Must include at least one identifying field.

{
  "full_name": "Sean Franklin",
  "given_name": "Sean",
  "family_name": "Franklin",
  "organization": "Acme Inc",
  "phones": [{ "value": "+14155551234", "label": "mobile" }],
  "emails": [{ "value": "sean@acme.example", "label": "work" }]
}

Field	Type	Notes
`full_name`	string	Formatted display name.
`given_name`	string	First name.
`family_name`	string	Last name.
`organization`	string	Org / company name.
`phones`	object[]	Each `{ value: <E.164>, label?: string }`.
`emails`	object[]	Each `{ value, label?: string }`.

string

Raw vCard payload (begins with BEGIN:VCARD). Use this when you already produce vCards elsewhere.

Response fields

string

The chat the card was sent into.

string

Always "sent" on success.

Errors

Code	HTTP	When
`1001`	400	Missing `contact` and `vcard_text` (request body needs one of them).
`1002`	400	`contact` has no identifying field, or fields were supplied in an unsupported shape.
`1004`	400	Invalid JSON body.
`2002`	404	Chat not found. On first-touch with no existing chat, address the call with `body.to` instead of `{id}`.
`4001`	502	Delivery failed.
`4099`	501	No pinned line, or the line does not support contact bubbles.

See the full error code reference.

Get started

Messages

Chats

Group chats

Contact sharing

Webhooks and events

Reference

Send a contact card

Addressing the recipient

Request

Response

Path parameters

Body

Response fields

Errors

See also

​Addressing the recipient

​Request

​Response

​Path parameters

​Body

​Response fields

​Errors

​See also

Addressing the recipient

Request

Response

Path parameters

Body

Response fields

Errors

See also