Skip to main content
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

FieldRequiredDescription
agentSlugone of agentSlug or agentIdStable slug for a PAM-managed SMS agent, such as sms-recall, sms-retention, or sms-declined-services.
agentIdone of agentSlug or agentIdUUID of a specific SMS agent.
toNumberyesCustomer phone number in E.164 format.
fromNumberPAM-managed agents onlySender phone number in E.164 format. For custom agents with a configured number, PAM uses the agent’s number.
welcomeMessagePAM-managed agents onlyExact first SMS body sent to the customer.
dynamicVariablesPAM-managed recall, retention, and declined-services agents onlyPublic string variables used to build the SMS agent context and tools. See PAM Agents for the required variables for each managed agent.
metadatanoOpaque reconciliation data stored with the conversation.
externalReferenceIdnoOpaque 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.
idempotencyKeynoStable key for safely retrying this create request.
webhookUrlnoHTTPS 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

StatusMeaning
queuedPAM created the conversation, but the opening SMS has not completed provider dispatch yet.
in_progressThe opening SMS was accepted by the provider and the conversation is open.
completedThe conversation ended normally. Check endReason for why it ended.
failedThe conversation could not start or hit an unrecoverable error.
cancelledThe conversation was cancelled before normal completion.

​
Lifecycle Webhooks

Subscribe to these events to follow the conversation:
EventWhen it fires
sms.message_sentAn outbound SMS has been sent and persisted, including the opening message.
sms.message_receivedAn inbound SMS from the customer has been persisted.
sms.message_delivery_updatedThe provider reported a canonical delivery status update for an outbound SMS.
sms.tool_call_invocationThe assistant invoked a tool during the SMS loop.
sms.tool_call_resultA 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.