Skip to main content
POST
/
sms-conversations
Create an SMS conversation
curl --request POST \
  --url https://api.pamhq.com/v1/sms-conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
}
'
import requests

url = "https://api.pamhq.com/v1/sms-conversations"

payload = {
    "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"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
  })
};

fetch('https://api.pamhq.com/v1/sms-conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pamhq.com/v1/sms-conversations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pamhq.com/v1/sms-conversations"

	payload := strings.NewReader("{\n  \"agentSlug\": \"sms-recall\",\n  \"toNumber\": \"+15555550199\",\n  \"fromNumber\": \"+15555550123\",\n  \"welcomeMessage\": \"Hi Ada, this is PAM Motors following up on your service recall.\",\n  \"dynamicVariables\": {\n    \"contact_first_name\": \"Ada\",\n    \"contact_last_name\": \"Lovelace\",\n    \"dealership_name\": \"PAM Motors\",\n    \"recall_id\": \"24V-123\",\n    \"service_ids\": \"RECALL_SERVICE\",\n    \"vin\": \"1HGBH41JXMN109186\",\n    \"vehicle_year\": \"2021\",\n    \"vehicle_make\": \"Honda\",\n    \"vehicle_model\": \"Accord\"\n  },\n  \"metadata\": {\n    \"externalContactId\": \"contact_123\"\n  },\n  \"externalReferenceId\": \"touchpoint_123\",\n  \"idempotencyKey\": \"sms_01HV7K4ZD3Q9X8P1M8Y2K9A0BC\",\n  \"webhookUrl\": \"https://partner.example.com/pam/webhooks\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.pamhq.com/v1/sms-conversations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agentSlug\": \"sms-recall\",\n  \"toNumber\": \"+15555550199\",\n  \"fromNumber\": \"+15555550123\",\n  \"welcomeMessage\": \"Hi Ada, this is PAM Motors following up on your service recall.\",\n  \"dynamicVariables\": {\n    \"contact_first_name\": \"Ada\",\n    \"contact_last_name\": \"Lovelace\",\n    \"dealership_name\": \"PAM Motors\",\n    \"recall_id\": \"24V-123\",\n    \"service_ids\": \"RECALL_SERVICE\",\n    \"vin\": \"1HGBH41JXMN109186\",\n    \"vehicle_year\": \"2021\",\n    \"vehicle_make\": \"Honda\",\n    \"vehicle_model\": \"Accord\"\n  },\n  \"metadata\": {\n    \"externalContactId\": \"contact_123\"\n  },\n  \"externalReferenceId\": \"touchpoint_123\",\n  \"idempotencyKey\": \"sms_01HV7K4ZD3Q9X8P1M8Y2K9A0BC\",\n  \"webhookUrl\": \"https://partner.example.com/pam/webhooks\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.pamhq.com/v1/sms-conversations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agentSlug\": \"sms-recall\",\n  \"toNumber\": \"+15555550199\",\n  \"fromNumber\": \"+15555550123\",\n  \"welcomeMessage\": \"Hi Ada, this is PAM Motors following up on your service recall.\",\n  \"dynamicVariables\": {\n    \"contact_first_name\": \"Ada\",\n    \"contact_last_name\": \"Lovelace\",\n    \"dealership_name\": \"PAM Motors\",\n    \"recall_id\": \"24V-123\",\n    \"service_ids\": \"RECALL_SERVICE\",\n    \"vin\": \"1HGBH41JXMN109186\",\n    \"vehicle_year\": \"2021\",\n    \"vehicle_make\": \"Honda\",\n    \"vehicle_model\": \"Accord\"\n  },\n  \"metadata\": {\n    \"externalContactId\": \"contact_123\"\n  },\n  \"externalReferenceId\": \"touchpoint_123\",\n  \"idempotencyKey\": \"sms_01HV7K4ZD3Q9X8P1M8Y2K9A0BC\",\n  \"webhookUrl\": \"https://partner.example.com/pam/webhooks\"\n}"

response = http.request(request)
puts response.read_body
{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "conversationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "providerMessageId": "<string>"
  },
  "meta": {
    "requestId": "<string>"
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "meta": {
    "requestId": "<string>"
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "meta": {
    "requestId": "<string>"
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "meta": {
    "requestId": "<string>"
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "meta": {
    "requestId": "<string>"
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "meta": {
    "requestId": "<string>"
  }
}

Authorizations

​
Authorization
string
header
default:pk_live_your_api_key
required

API key provided as Authorization: Bearer <key>.

Body

application/json

Select exactly one agent. Use agentSlug for PAM-managed agents, or agentId for a specific custom agent.

​
agentId
string<uuid>
required

Specific custom agent id.

​
toNumber
string
required

Phone number in E.164 format.

Pattern: ^\+\d{7,15}$
​
agentSlug
string

Stable slug for a PAM-managed agent.

Required string length: 1 - 255
​
fromNumber
string

Required when you use agentSlug. Ignored when the selected agent has a configured phone number.

Pattern: ^\+\d{7,15}$
​
welcomeMessage
string

Exact first SMS body. Required when you use a PAM-managed SMS agent.

​
dynamicVariables
object

Required when you use a PAM-managed recall, retention, or declined-services SMS agent. Send only public variables documented in the Agents guide; generated prompt blocks are internal.

​
metadata
object

Opaque metadata stored with the conversation for reconciliation.

​
externalReferenceId
string

Optional opaque caller-owned reference echoed as top-level externalReferenceId on webhook payloads. PAM does not interpret this value, does not require it to be globally unique, and does not use it as an idempotency key.

Required string length: 1 - 255
​
idempotencyKey
string

Stable key for safely retrying this create request.

Required string length: 1 - 255
​
webhookUrl
string<uri>

Optional HTTPS destination for webhook events from this SMS conversation. The URL overrides only this conversation's destination; event subscriptions, custom headers, and signing secret still come from the matching webhook registration.

Pattern: ^https://

Response

SMS conversation created

​
data
object
​
meta
object