Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pam.ai/llms.txt

Use this file to discover all available pages before exploring further.

Use POST /v1/sms-conversations to create a single SMS conversation outside of a campaign. 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": "recall-sms",
    "toNumber": "+15555550199",
    "fromNumber": "+15555550123",
    "welcomeMessage": "Hi Ada, this is PAM Motors following up on your service recall.",
    "dynamicVariables": {
      "customerName": "Ada",
      "dealershipName": "PAM Motors",
      "recallId": "24V-123"
    }
  }'
Successful requests return 201 Created: 
{
  "data": {
    "conversationId": "b7ee8d1b-5e3e-4a1a-8f0a-9e2a4f8f1aa2",
    "providerMessageId": "403d5977-fc3b-4b9f-9d7b-9f7bb0c9d8e1",
    "status": "in_progress"
  },
  "meta": {
    "request_id": "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.
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.
dynamicVariablesnoString variables available to the SMS agent and tools.
Your API key determines the client organization for attribution and billing. Do not send clientOrgId in the request body.

​
Opening Message Rules

PAM-managed SMS agents require welcomeMessage. Build the message from your customer, dealership, and workflow 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.

​
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. PAM may also close inactive SMS conversations automatically with inactivity_timeout.

​
Common Errors

  • 400 validation_error — invalid phone format, 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.
  • 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.