To log text messages in a CRM, you capture each inbound and outbound text as an event, match it to a contact by phone number, and write one timeline entry per message with a stable id so retries never create duplicates. The pattern is simple. The edge cases (duplicates, ordering, deleted contacts) are where most integrations go wrong.

One honest note first: Ready does not log every text to a CRM timeline on its own. That's still to build on our side. What exists today is a set of pieces you can combine: webhooks for new events, a message list API for backfill, and App Library CRM connections that can write a note to a contact's timeline. This guide shows the pattern and where each piece fits.

What a timeline entry needs

The direct answer: store the direction, the body, the time, the phone number in E.164, the message id and the sender, and link it to a contact.

FieldSourceNotes
Message idThe message recordYour dedupe key; never generate your own
DirectionInbound or outboundShow it differently in the UI
BodyThe message textKeep media as a link, not inline data
TimestampThe message timeStore in UTC, display in the viewer's zone
Phone numberE.164Match key to the contact
SenderRep, automation or contactNeeded for reporting later
StatusSent, delivered, failedUpdates after the first write

For a deeper take on how to model these records, see our post on the SMS conversation data model for CRM developers.

Three ways to get texts into the timeline

The direct answer: use webhooks for live events, the message list API to backfill gaps, and a CRM connection only for the notes it can write.

  1. Webhooks. Ready sends a webhook when something happens, such as a reply arriving. Your endpoint verifies it, writes the timeline entry and answers quickly. The API quickstart covers the key, first send and webhook setup, and the docs are the source of truth for payload fields. We're deliberately not copying field names into a blog post, because code copied from a post goes stale.
  2. The message list. GET /v1/messages returns messages and pages with before_id. Use it to backfill after downtime and to reconcile what your timeline holds against what was actually sent. See the messages API docs.
  3. App Library CRM connections. Ready's App Library connects to Close, HubSpot, Pipedrive, Salesforce, Zoho CRM. A connection can create or update a contact, add a note to the contact's timeline, move a deal to a stage, and start a Ready flow when a new contact appears in the CRM. That's useful for key moments, but it isn't a full mirror of every text. Ready has no listing inside those CRMs' own marketplaces; the connection runs from Ready's side.

If you use GoHighLevel, the native integration syncs inbound and outbound messages in both directions per sub-account, so the conversation shows in GHL without any of this. Our post on native versus webhook SMS sync in GoHighLevel compares the two.

The write path, step by step

The direct answer: treat each webhook as at-least-once delivery, and make the write idempotent.

  1. Verify the request the way the docs describe and reject anything that fails.
  2. Return a success response fast. Do the heavy work after you've saved the raw event to a queue.
  3. Normalize the number to E.164 and look up the contact.
  4. Upsert the timeline entry keyed on the message id. A second delivery of the same event should change nothing.
  5. If the status changes later (sent, then delivered, or failed), update the same entry. Don't add a second one.
  6. If a webhook fails past your retry limit, park it in a dead letter queue so you can replay it.

Events can arrive out of order. A "delivered" update may reach you before the "sent" one you haven't stored yet. Keep the entry and apply states by rank, so a later state never gets overwritten by an earlier one that arrived late.

The hard cases

The direct answer: unknown numbers, shared numbers and deleted contacts account for most timeline bugs.

  • Unknown sender. An inbound text from a number with no contact. Create a lead stub, or park it in an unmatched list for a human. Don't drop it.
  • Same number, two contacts. A household or a company line may map to several people. Pick a rule (most recently active, or the open deal's owner) and write it down.
  • Contact merged or deleted. Keep message ids stable, and re-point entries on merge. If a contact is deleted, decide whether history goes too. Deleting a contact in Ready also removes that contact's call recordings and transcripts.
  • Group and media texts. Store the media as a link and the participant list on the entry.
  • Opt-outs. Log the STOP as an entry, then update the contact's text permission. Ready honors the opt-out automatically; GET /v1/opt-outs/:phone tells you the state for one number.

A small worked example

The direct answer: an hourly reconciliation catches what live webhooks miss.

Assumptions for illustration: your product sends and receives about 2,000 texts in a day, and you store one timeline entry per message. Each text is one segment. Your reconciliation job pages GET /v1/messages back from the newest id, stops at the last id it stored, and compares counts.

  • Expected entries for the day: 2,000.
  • Entries in your timeline at the check: 1,994.
  • The job finds 6 message ids it never stored (an outage window) and inserts them.

That's six inserts, no duplicates, because the insert is keyed on the message id. Without the key, the same job could add hundreds of duplicates after a retry storm.

When the CRM write is the wrong move

The direct answer: don't write low-value events as timeline entries.

A timeline with every delivery receipt is noise. Write the message itself as an entry, and keep status changes as small updates on that entry. If you only need a summary, such as "3 texts this week, last reply Tuesday," compute it from the message list API and show it as a field on the contact. Reps read summaries; analysts read the full history.

Frequently asked questions

Does Ready log texts to my CRM automatically?

Not for every text. Ready's App Library CRM connections can add a note to a contact's timeline, create or update a contact and move a deal. A full automatic log of every message is still to build, so use webhooks and the message list API for that today.

How do I avoid duplicate timeline entries?

Key every write on the message id and make it an upsert. Delivery can repeat, so the second write should be a no-op.

Can I backfill old texts?

Yes. Page through GET /v1/messages with before_id and insert any id you don't already have. Run it on a schedule to catch gaps.

Next step

Start with the smallest version: one webhook endpoint, one upsert keyed on the message id, and one reconciliation job. Add the App Library connection only for the moments a rep should see as a note. To try the sending side, sign up and read the inbound webhooks guide before you wire your endpoint.