iMessage API for CRM integration

The pitch is obvious: your CRM knows who your customers are and what stage they are at, so it should be able to text them. The half-built version is equally common — outbound works, inbound is lost, and within a month your team is answering replies on someone's personal phone while the CRM shows a one-sided conversation.

The integration has four parts, not one

Most teams build the first and discover the other three in production.

1. 01Outbound. A CRM workflow triggers a message. Easy, and where everyone starts.
2. 02Inbound. Replies arrive on a webhook and must be written to the right contact record. This is the part that gets skipped.
3. 03Identity resolution. A reply arrives from +15551234567. Which contact is that? Phone formats in CRMs are inconsistent enough that naive matching fails often.
4. 04Timeline sync. Both directions logged against the contact, so anyone opening the record sees the whole conversation.

Identity resolution that actually works

import { parsePhoneNumber } from "libphonenumber-js";
 
export function normalise(raw: string, defaultCountry = "US") {
  try {
    const parsed = parsePhoneNumber(raw, defaultCountry);
    return parsed?.isValid() ? parsed.format("E.164") : null;
  } catch {
    return null;
  }
}
 
export async function resolveContact(from: string) {
  const e164 = normalise(from);
  if (!e164) return null;
 
  // Exact match on the normalised column is the only reliable lookup.
  const contact = await crm.contacts.findByPhone(e164);
  if (contact) return contact;
 
  // A reply from an unknown number is a real event, not an error — someone
  // forwarded your text, or the contact is under a second number.
  return await crm.contacts.create({
    phone: e164,
    source: "imessage_inbound",
    // Flag rather than guess. A human decides whether to merge.
    needsReview: true,
  });
}

Writing both directions to the timeline

The value of the integration is the record, not the send. If a salesperson opens a contact and sees only what was sent, the integration has failed at its actual job.

export async function logOutbound(contactId: string, text: string, messageId: string) {
  await crm.engagements.create({
    contactId,
    type: "message",
    direction: "outbound",
    channel: "imessage",
    body: text,
    externalId: messageId, // lets a later delivery event find this row
    occurredAt: new Date().toISOString(),
  });
}
 
export async function logInbound(contactId: string, text: string, messageId: string) {
  await crm.engagements.create({
    contactId,
    type: "message",
    direction: "inbound",
    channel: "imessage",
    body: text,
    externalId: messageId,
    occurredAt: new Date().toISOString(),
  });
 
  // A reply is a signal, not just a record. Route it to whoever owns the deal.
  await crm.tasks.create({
    contactId,
    title: "Replied by text",
    assigneeId: await crm.contacts.ownerOf(contactId),
    dueAt: new Date(Date.now() + 15 * 60_000).toISOString(),
  });
}

The major CRMs, specifically

What to check before you commit

• Does the provider push inbound to a webhook, or do you have to poll? Polling makes conversational use unpleasant.
• Does it send delivery events you can attach to the timeline entry you already wrote?
• Can you send from multiple lines, so a rep's messages come from their own number rather than a shared one?
• Does opt-out propagate to your CRM, or only to the provider's suppression list? If only theirs, your workflows will keep trying.
• Can you tag links per campaign so the CRM shows what a contact actually clicked? The UTM builder generates them.

For the sales motion built on top of this, see iMessage for B2B sales; for two-way conversation design, two-way texting.