SMS Conversations - PAM Outbound API

Use POST /v1/sms-conversations to create a single SMS conversation. PAM sends the first outbound SMS immediately, then continues the conversation through inbound replies, assistant turns, and optional tool calls.

Create an SMS Conversation

curl https://api.pamhq.com/v1/sms-conversations \
  -X POST \
  -H "Authorization: Bearer $PAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentSlug": "sms-recall",
    "toNumber": "+15555550199",
    "fromNumber": "+15555550123",
    "welcomeMessage": "Hi Ada, this is PAM Motors following up on your service recall.",
    "dynamicVariables": {
      "contact_first_name": "Ada",
      "contact_last_name": "Lovelace",
      "dealership_name": "PAM Motors",
      "recall_id": "24V-123",
      "service_ids": "RECALL_SERVICE",
      "vin": "1HGBH41JXMN109186",
      "vehicle_year": "2021",
      "vehicle_make": "Honda",
      "vehicle_model": "Accord"
    },
    "metadata": {
      "externalContactId": "contact_123"
    },
    "externalReferenceId": "touchpoint_123",
    "idempotencyKey": "sms_01HV7K4ZD3Q9X8P1M8Y2K9A0BC",
    "webhookUrl": "https://partner.example.com/pam/webhooks"
  }'

Successful requests return 201 Created:

{
  "data": {
    "id": "b7ee8d1b-5e3e-4a1a-8f0a-9e2a4f8f1aa2",
    "conversationId": "b7ee8d1b-5e3e-4a1a-8f0a-9e2a4f8f1aa2",
    "providerMessageId": "403d5977-fc3b-4b9f-9d7b-9f7bb0c9d8e1",
    "status": "in_progress"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

in_progress means the opening SMS was accepted by the provider and persisted by PAM.

Request Fields

Field	Required	Description
`agentSlug`	one of `agentSlug` or `agentId`	Stable slug for a PAM-managed SMS agent, such as `sms-recall`, `sms-retention`, or `sms-declined-services`.
`agentId`	one of `agentSlug` or `agentId`	UUID of a specific SMS agent.
`toNumber`	yes	Customer phone number in E.164 format.
`fromNumber`	PAM-managed agents only	Sender phone number in E.164 format. For custom agents with a configured number, PAM uses the agent’s number.
`welcomeMessage`	PAM-managed agents only	Exact first SMS body sent to the customer.
`dynamicVariables`	PAM-managed recall, retention, and declined-services agents only	Public string variables used to build the SMS agent context and tools. See PAM Agents for the required variables for each managed agent.
`metadata`	no	Opaque reconciliation data stored with the conversation.
`externalReferenceId`	no	Opaque caller-owned reference echoed as top-level `externalReferenceId` on webhook events for this conversation. PAM does not interpret this value. It does not need to be globally unique and is not a replacement for `idempotencyKey`.
`idempotencyKey`	no	Stable key for safely retrying this create request.
`webhookUrl`	no	HTTPS URL that receives webhook events for this SMS conversation instead of the default webhook registration URL. Event subscriptions, custom headers, and signing secret still come from your matching webhook registration.

Your API key determines the client organization for attribution and billing. Do not send clientOrgId in the request body. Use externalReferenceId when your system needs to map webhooks back to one of your own objects, such as a touchpoint, campaign, or workflow run. PAM stores the value and echoes it on webhooks when provided. For PAM-managed agents, PAM generates internal prompt context blocks from the submitted dynamicVariables plus server-owned client configuration. Those generated context blocks are not returned by SMS conversation GET or list responses.

Opening Message Rules

PAM-managed SMS agents require welcomeMessage. Build the message from your customer, dealership, and outreach context, then pass the resolved text in the create request. Custom SMS agents can use their configured opening behavior. For those agents, PAM can generate the opening turn from the agent configuration and dynamicVariables.

Supersede Behavior

Only one open SMS conversation should exist for the same (fromNumber, toNumber) pair. When you create a new SMS conversation for a pair that already has open conversations, PAM closes the older open conversations with:

superseded_by_new_conversation

Use the new conversationId returned by the create response for all future reconciliation.

List Conversations

Use GET /v1/sms-conversations to list SMS conversations for your organization.

curl "https://api.pamhq.com/v1/sms-conversations?limit=20" \
  -H "Authorization: Bearer $PAM_API_KEY"

You can filter by status, agentId, toNumber, fromNumber, createdAfter, and createdBefore. Results are cursor-paginated:

{
  "data": [
    {
      "id": "b7ee8d1b-5e3e-4a1a-8f0a-9e2a4f8f1aa2",
      "conversationId": "b7ee8d1b-5e3e-4a1a-8f0a-9e2a4f8f1aa2",
      "status": "in_progress",
      "agentId": "2c4a1e72-7a5d-4b6e-9c2a-01a78b7b3f3f",
      "agentVersionId": "7a9c7b3e-8d0f-4c40-a156-dcc78c89b127",
      "fromNumber": "+15555550123",
      "toNumber": "+15555550199",
      "dynamicVariables": {
        "contact_first_name": "Ada",
        "contact_last_name": "Lovelace",
        "dealership_name": "PAM Motors",
        "recall_id": "24V-123"
      },
      "metadata": {
        "externalContactId": "contact_123"
      },
      "startedAt": "2026-04-10T14:00:00.000Z",
      "endedAt": null,
      "endReason": null,
      "createdAt": "2026-04-10T14:00:00.000Z",
      "updatedAt": "2026-04-10T14:00:00.000Z"
    }
  ],
  "meta": {
    "requestId": "req_abc123",
    "pagination": {
      "cursor": null,
      "hasMore": false
    }
  }
}

If hasMore is true, pass the returned cursor in the next request.

Get Conversation Status

Use GET /v1/sms-conversations/{id} to get the current status for one SMS conversation.

curl https://api.pamhq.com/v1/sms-conversations/b7ee8d1b-5e3e-4a1a-8f0a-9e2a4f8f1aa2 \
  -H "Authorization: Bearer $PAM_API_KEY"

{
  "data": {
    "id": "b7ee8d1b-5e3e-4a1a-8f0a-9e2a4f8f1aa2",
    "conversationId": "b7ee8d1b-5e3e-4a1a-8f0a-9e2a4f8f1aa2",
    "status": "completed",
    "agentId": "2c4a1e72-7a5d-4b6e-9c2a-01a78b7b3f3f",
    "agentVersionId": "7a9c7b3e-8d0f-4c40-a156-dcc78c89b127",
    "fromNumber": "+15555550123",
    "toNumber": "+15555550199",
    "dynamicVariables": {
      "contact_first_name": "Ada",
      "contact_last_name": "Lovelace",
      "dealership_name": "PAM Motors",
      "recall_id": "24V-123"
    },
    "metadata": {
      "externalContactId": "contact_123"
    },
    "startedAt": "2026-04-10T14:00:00.000Z",
    "endedAt": "2026-04-10T14:45:00.000Z",
    "endReason": "inactivity_timeout",
    "createdAt": "2026-04-10T14:00:00.000Z",
    "updatedAt": "2026-04-10T14:45:00.000Z"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

These read endpoints are useful when a webhook is delayed, retried, or missed by your system.

Status Meanings

Status	Meaning
`queued`	PAM created the conversation, but the opening SMS has not completed provider dispatch yet.
`in_progress`	The opening SMS was accepted by the provider and the conversation is open.
`completed`	The conversation ended normally. Check `endReason` for why it ended.
`failed`	The conversation could not start or hit an unrecoverable error.
`cancelled`	The conversation was cancelled before normal completion.

Lifecycle Webhooks

Subscribe to these events to follow the conversation:

Event	When it fires
`sms.message_sent`	An outbound SMS has been sent and persisted, including the opening message.
`sms.message_received`	An inbound SMS from the customer has been persisted.
`sms.message_delivery_updated`	The provider reported a canonical delivery status update for an outbound SMS.
`sms.tool_call_invocation`	The assistant invoked a tool during the SMS loop.
`sms.tool_call_result`	A tool result was persisted.

Delivery updates are canonical PAM states, not raw provider events. A message can receive duplicate or out-of-order provider signals; PAM normalizes those before emitting sms.message_delivery_updated.

Close a Conversation

Use POST /v1/sms-conversations/{id}/close to manually close an open SMS conversation.

curl https://api.pamhq.com/v1/sms-conversations/b7ee8d1b-5e3e-4a1a-8f0a-9e2a4f8f1aa2/close \
  -X POST \
  -H "Authorization: Bearer $PAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "customer_resolved"
  }'

If reason is omitted, PAM uses admin_closed.

Common Errors

400 validation_error — invalid phone format, invalid or non-HTTPS webhookUrl, both agentId and agentSlug were provided, or neither was provided.
400 validation_error — fromNumber is missing for a PAM-managed agent.
400 validation_error — welcomeMessage is missing or blank for a PAM-managed SMS agent.
400 validation_error — a managed agent request is missing required dynamicVariables.
401 unauthorized — missing, expired, revoked, or invalid API key.
404 not_found — the agent could not be resolved or the conversation does not belong to the authenticated client.

​Create an SMS Conversation

​Request Fields

​Opening Message Rules

​Supersede Behavior

​List Conversations

​Get Conversation Status

​Status Meanings

​Lifecycle Webhooks

​Close a Conversation

​Common Errors