iMessage business name and photo API

Set your business name and photo once with PUT /api/imessage/profile. Every conversation shares them, so customers see your brand in Messages instead of a bare number.

Included on Pro at $49/month per number. Limits apply.

+1 (805) 555-0142
Your booking is confirmed for Friday at 3.
Thank you!

"profile": null

Your name instead of a number.

Customers see your name and photo in the thread header. They can save it to their contacts.

Your name goes out with your first text.

Once a profile is set, every message you send shares it for you. It goes with the first message of a conversation, and again after you change it.

  1. First message
    Your booking is confirmed.

    The name and photo go with it.

  2. Later messages
    See you Friday.

    The card is not sent again.

  3. After you change it
    Your table is ready.

    The next message shares the new card, so existing contacts get it too.

A square photo, 600 pixels or more.

The photo is a JPEG or PNG under 3 MB. The name is up to 64 characters.

A square logo for Harbor Dental with a circle marking the part that shows
Your photo
How it shows

How it works

  1. Set the profile once. PUT /api/imessage/profile with a name and an image_b64. We apply it to the line before we reply, so the call can take a few seconds. The status is profile_set.
  2. Send as usual. Every message you send shares it, in the background right after the message. They see “<name> shared a name and photo with you”.
  3. Share again if you need to. POST /api/imessage/profile/share with to re-shares on demand, and it covers conversations they started. force: true sends it to someone who already has it.
Set, share, read
PUT /api/imessage/profile
{"name": "Harbor Dental", "image_b64": "<base64 JPEG or PNG>"}

// share it again on demand
POST /api/imessage/profile/share
{"to": "+18055559876"}

// read what is set
GET /api/imessage/line
{"profile": {"name": "Harbor Dental", "has_photo": true,
             "updated_at": "..."}}
profile is null until the first PUT. The full reference is in our docs.

Calls

Name and photo calls
CallWhat it does
PUT /api/imessage/profileSets the name and photo. After the first call the photo is optional, and the current one is kept.
POST /api/imessage/profile/shareShares the card with one recipient. Status profile_shared. Add line_id to share from one number when you have several.
GET /api/imessage/lineReports the current profile as name, has_photo and updated_at, or null before the first PUT.
GET /api/imessage/profile/photoReturns the current photo as image/jpeg or image/png, and 404 when there is none.
MCP toolset_profile takes name and image_b64, the same as PUT. It works before you pay.

Limits and plans

The name

Up to 64 characters, and the only name recipients see. It becomes the contact’s first name. There is no last name.

The photo

A JPEG or PNG under 3 MB. A <code>data:image/...;base64,</code> prefix is fine. Square images of 600 px or more look best.

422 invalid_request

The name or photo is not acceptable. <code>error.fields</code> names <code>name</code> or <code>image_b64</code>.

409 no_profile

You shared before you set a profile. Call <code>PUT /api/imessage/profile</code> first.

No new contact

Sharing is iMessage-only and counts toward nothing. It is not a new contact.

Group chats

A group send skips the automatic share. It is a rule for one-to-one conversations.

Several numbers

The name and photo belong to a line group. <code>PUT /api/imessage/profile?group=lg_...</code> sets every line of that group. Without a group it sets every line to the same name and photo. Each contact sees the card of the line their conversation is on.

Testing a change

Delete the conversation with <code>DELETE /api/imessage/conversations/{handle}</code> or in the console, then text the number again. The first message shares the current card.

Plans

Name and photo sharing is included on Pro, at $49/month per number with 5 new contacts a day per number. Growth has 25+ new contacts a day per number. Details are on the iMessage API page.

Questions

Can I set my business name and photo on iMessage?

Yes. Send PUT /api/imessage/profile with a name and an image_b64. After that, every message you send shares them, so your number shows up as your brand instead of a bare number.

What do customers see?

They see “<name> shared a name and photo with you” and can save it to their contacts. The name becomes the contact’s first name. There is no last name.

How big can the name and photo be?

The name is up to 64 characters. The photo is a JPEG or PNG under 3 MB, and square images of 600 px or more look best. Anything else returns 422 invalid_request, and error.fields names name or image_b64.

When is the profile shared?

Automatically with the first message of a conversation, and again with the next message after you change the name or photo. POST /api/imessage/profile/share re-shares on demand, and force: true sends it again to someone who already has it.

Does sharing a name and photo count as a new contact?

No. Sharing is iMessage-only and counts toward nothing. Reactions, typing indicators and chat backgrounds do not count either.

Do group chats and several numbers share it?

A group send skips the automatic share. With more than one number, the name and photo belong to a line group, and PUT /api/imessage/profile?group=lg_... sets every line of that group. Each contact sees the card of the line their conversation is on.

How do I test a change?

Delete the conversation and text the number again. The first message of a conversation always shares the current name and photo, so the new card shows up fresh.

Is it included in my plan?

Yes. Name and photo sharing is included on Pro, which is $49/month per number.

Put your name on it

Get a number, then send PUT /api/imessage/profile with your name and photo.