> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revring.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Two-way texting

> Let your agents hold text conversations and send SMS outside of a call

Beyond texting during a call, your agents can hold full back-and-forth text conversations and send messages outside of a call, all from the same number they call from.

There are two parts:

* **Incoming texts:** when someone texts your number, your agent can reply automatically with AI, or RevRing can forward the message to your own system.
* **Sending texts:** send a message from your own automations (for example, following up when a lead does not answer a call) using the [Send Message API](/api-reference/messages/send).

## Replying to incoming texts

Each agent chooses what happens when a text comes in:

<CardGroup cols={2}>
  <Card title="Reply automatically with AI" icon="robot">
    RevRing writes a reply using the agent's SMS prompt and the recent conversation, then sends it back. Hands-off for you.
  </Card>

  <Card title="Notify your webhook" icon="bell">
    RevRing forwards each incoming text to a URL you choose, so your own system can decide how to respond.
  </Card>
</CardGroup>

<Note>
  With **Notify your webhook**, RevRing POSTs a `message_received` event to your URL. See [Inbound Message Webhook](/platform/webhooks#inbound-message-webhook) for the exact payload and a code sample.
</Note>

### The SMS prompt

For automatic replies, the agent uses its **SMS prompt** (set on the agent's **Messaging** tab) when you've added one, and otherwise falls back to the agent's main prompt — so auto-reply works out of the box. Add an SMS prompt only when you want texting to have its own tone, separate from calls. RevRing keeps the recent conversation with each contact, so replies stay in context.

### Knowledge bases, tools, and what texting knows

Text replies use the same [knowledge bases](/platform/knowledge-bases) and [custom tools](/platform/tools) as the agent's calls — nothing separate to set up. Attach a knowledge base or add a tool to the agent, and texting picks it up automatically:

* **Knowledge bases** — replies look up relevant information from the agent's attached knowledge bases, using the agent's existing retrieval settings.
* **Custom tools** — when the conversation calls for it, the agent invokes its custom tools (booking, callbacks, live lookups against your systems) and uses the result in its reply. Tool webhooks receive the same request shape as on a call, with `callId` set to `null` and `conversationId` and `channel` (`"sms"`) identifying the thread instead. Call-only tools (phone transfer, keypad tones) stay call-only.
* **Current date and time** — every reply knows the current date and time in the agent's timezone, so rules like opening hours apply on their own. `{{current_time}}` and the agent's default variables also render in the SMS prompt with `{{variable}}` templating, the same as on calls.

This applies to automatic replies and to API sends with `generate: true` when an `agentId` is provided.

### Set up incoming texts

<Steps>
  <Step title="Connect a provider and choose it on the agent">
    Follow [Messaging](/platform/messaging) to connect a provider, then open the agent's **Messaging** tab and select the connection.
  </Step>

  <Step title="Choose what happens on an incoming text">
    On the **Messaging** tab, set **When a text comes in** to either reply automatically or notify your webhook. The SMS prompt is optional — auto-reply uses the agent's main prompt if you leave it blank.
  </Step>

  <Step title="Assign the number to the agent">
    On the agent's **Numbers** tab, add the number that will receive texts. Incoming texts are routed to the agent that owns the number.
  </Step>

  <Step title="Point your provider's inbound webhook to RevRing">
    In your provider, set the inbound message webhook for your Messaging Service to:

    ```
    https://api.revring.ai/webhooks/twilio/inbound
    ```
  </Step>
</Steps>

<Note>
  To receive texts on a number, assign it to an agent, the same way you do to receive calls. That keeps calls and texts for one number flowing to the same agent.
</Note>

## Sending texts from your own automations

Use the [Send Message API](/api-reference/messages/send) to send an SMS outside of a call. You can either:

* Send a **raw message** by passing `body`, or
* Have RevRing **compose the message** with AI by passing `generate: true`. It uses the agent's SMS prompt and the ongoing conversation with that contact, or a history you pass inline with `messages` if you prefer to manage memory yourself.

This fits reseller and CRM workflows well. For example, when a lead does not answer a call, your automation platform can trigger a follow-up text.

<Note>
  Messages you send through the API join the same conversation as incoming texts for that contact. So if you send an opener and the contact replies, an automatic reply already has the context of what you sent.
</Note>

<Note>
  You bring your own provider account, so messages are sent from your numbers and billed to you by your provider, at your provider's rates.
</Note>

## Managing conversations

RevRing keeps a managed conversation for each contact, on each of your numbers. This is the memory behind automatic replies and AI-composed sends: the recent back-and-forth that keeps responses in context.

* **Automatic idle reset.** After 30 days with no messages, a conversation starts fresh on its own, so a contact who returns much later isn't answered with stale context. This window is configurable per agent.
* **Read the full thread.** Open any conversation on the **Conversations** page to see the whole back-and-forth. When the agent used a tool or its knowledge base to answer, that activity is shown right under the reply, so you can see what the agent did and where its answer came from. The same detail is available on the API with `GET /v1/conversations/{id}`, where each generated reply includes a `meta` object listing the tools it called and the knowledge base sources it cited.
* **Clear a conversation.** See active threads on the **Conversations** page in the dashboard, or with the [Conversations API](/api-reference/conversations/list). Clearing a thread deletes it and its logged messages, so the very next text from that contact starts a brand-new conversation.

Clearing is handy when you want to re-test an agent as if you were a new contact, or to forget a contact's history on request.

## Next steps

<CardGroup cols={2}>
  <Card title="Connect Messaging" icon="comments" href="/platform/messaging">
    Connect a provider and enable texting on a call
  </Card>

  <Card title="Send Message API" icon="code" href="/api-reference/messages/send">
    Send and generate messages programmatically
  </Card>

  <Card title="Web Widget" icon="comment-dots" href="/platform/web-widget">
    The same conversations as a chat bubble on your website
  </Card>
</CardGroup>