Contact Cards

Send vCards as iMessage contact cards

Send a contact card and the recipient sees a rich contact preview they can tap to save directly to their contacts, with call / text / email action buttons.

Send a contact card

Pass the contact fields directly to sendContactCard — the SDK generates the vCard, uploads it, and attaches it to a message in one call.

TypeScript

import { createClient } from "@messages-dev/sdk";

const client = createClient();

await client.sendContactCard({
  from: "[phone]",
  to: "[phone]",
  firstName: "Jane",
  lastName: "Doe",
  phones: [{ type: "cell", value: "[phone]" }],
  emails: [{ value: "[e-mail]" }],
  org: "Acme Corp",
  title: "Head of Engineering",
});

Include at least one phones or emails entry. iOS uses them to render the tappable action buttons (call, text, email) on the contact preview.

Supported fields

Field	Type	Description
firstName, lastName	string	Required. Used for both N and FN in the vCard.
phones	{ value, type? }[]	One or more phone numbers. type defaults to cell.
emails	{ value, type? }[]	One or more email addresses. type is optional.
org	string	Organization / company.
title	string	Job title.
url	string	Website.
address	{ street?, city?, region?, postalCode?, country?, type? }	Mailing address.
bday	string	Birthday, ISO YYYY-MM-DD.
note	string	Free-text note. Reserved characters (;, ,, newlines) are escaped automatically.
photo	string	File ID (file_...) of a JPEG or PNG uploaded via POST /v1/files. The SDK fetches it and embeds it inline in the vCard.
photoType	"JPEG" | "PNG"	Override photo mime type when auto-detection from the file’s magic bytes can’t determine it.
text	string	Optional message text sent alongside the card.
replyTo	string	Message ID or GUID to reply to.
filename	string	Override the uploaded .vcf filename. Default: <first>-<last>.vcf.

Add a contact photo

Upload the photo via POST /v1/files first, then pass the returned file ID as photo. The SDK downloads it, sniffs the image type (JPEG / PNG), and embeds it inline in the vCard.

import { readFileSync } from "node:fs";
import { createClient } from "@messages-dev/sdk";

const client = createClient();

const photo = await client.uploadFile({
  file: readFileSync("jane.jpg"),
  mimeType: "image/jpeg",
  filename: "jane.jpg",
});

await client.sendContactCard({
  from: "[phone]",
  to: "[phone]",
  firstName: "Jane",
  lastName: "Doe",
  phones: [{ type: "cell", value: "[phone]" }],
  photo: photo.id,
});

Keep photos small (under 100KB) for the best delivery experience. Large photos inflate the vCard significantly once base64-encoded.

Advanced: custom vCard

If you need fields that sendContactCard doesn’t expose (exotic TYPE combinations, custom X- extensions, multiple addresses), build the vCard yourself and send it via the file + attachment flow:

import { createClient } from "@messages-dev/sdk";

const client = createClient();

const vcard = [
  "BEGIN:VCARD",
  "VERSION:3.0",
  "N:Doe;Jane;;;",
  "FN:Jane Doe",
  "TEL;TYPE=CELL:[phone]",
  "EMAIL:[e-mail]",
  "END:VCARD",
].join("\r\n");

const file = await client.uploadFile({
  file: new Blob([vcard], { type: "text/vcard" }),
  filename: "jane-doe.vcf",
  mimeType: "text/vcard",
});

await client.sendMessage({
  from: "[phone]",
  to: "[phone]",
  attachments: [file.id],
});

vCard format reference

For reference when building custom vCards, a full-featured example:

BEGIN:VCARD
VERSION:3.0
N:Doe;Jane;;;
FN:Jane Doe
ORG:Acme Corp
TITLE:Head of Engineering
TEL;TYPE=CELL:[phone]
TEL;TYPE=WORK:[phone]
EMAIL:[e-mail]
URL:https://acme.com
ADR;TYPE=WORK:;;123 Main St;San Francisco;CA;94105;US
NOTE:Met at WWDC 2025
END:VCARD

Common fields

Field	Example	Description
N	Doe;Jane;;;	Last; First; Middle; Prefix; Suffix
FN	Jane Doe	Full display name
TEL;TYPE=CELL	[phone]	Mobile phone
TEL;TYPE=WORK	[phone]	Work phone
EMAIL	[e-mail]	Email address
ORG	Acme Corp	Organization
TITLE	Head of Engineering	Job title
URL	https://acme.com	Website
ADR;TYPE=WORK	;;123 Main St;City;ST;ZIP;US	Address
NOTE	Met at WWDC 2025	Free-text note
BDAY	1990-06-15	Birthday
PHOTO;ENCODING=b;TYPE=JPEG	<base64>	Inline photo

The MIME type for vCard files is text/vcard, the file extension is .vcf, and lines are joined with \r\n.