> ## 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. # Create an SMS conversation > Creates an SMS conversation and sends the opening outbound SMS. Creating a new conversation for the same from/to pair closes prior open SMS conversations for that pair. ## OpenAPI ````yaml /openapi/v1.json post /sms-conversations openapi: 3.0.3 info: title: PAM Outbound API version: 1.0.0 description: >- External API for creating outbound calls, starting SMS conversations, managing API keys, and receiving webhook events. servers: - url: https://api.pamhq.com/v1 description: Production security: - bearerApiKey: [] tags: - name: Calls description: Start and manage outbound voice calls. - name: SMS Conversations description: Start and manage outbound SMS conversations. - name: API Keys description: Create, list, inspect, and revoke API keys. - name: Webhooks description: Configure direct call and SMS conversation webhook destinations. - name: Webhook Events description: Canonical webhook payloads emitted by calls and SMS conversations. paths: /sms-conversations: post: tags: - SMS Conversations summary: Create an SMS conversation description: >- Creates an SMS conversation and sends the opening outbound SMS. Creating a new conversation for the same from/to pair closes prior open SMS conversations for that pair. operationId: createSmsConversation requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SmsConversationCreateRequest' examples: pamManagedAgent: summary: PAM recall SMS agent value: 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 responses: '201': description: SMS conversation created content: application/json: schema: $ref: '#/components/schemas/SmsConversationCreateResponse' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/ServerError' components: schemas: SmsConversationCreateRequest: allOf: - $ref: '#/components/schemas/AgentSelector' - type: object required: - toNumber properties: toNumber: $ref: '#/components/schemas/E164PhoneNumber' fromNumber: $ref: '#/components/schemas/E164PhoneNumber' description: >- Required when you use agentSlug. Ignored when the selected agent has a configured phone number. welcomeMessage: type: string description: >- Exact first SMS body. Required when you use a PAM-managed SMS agent. dynamicVariables: allOf: - $ref: '#/components/schemas/DynamicVariables' description: >- 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: type: object additionalProperties: true description: Opaque metadata stored with the conversation for reconciliation. externalReferenceId: type: string minLength: 1 maxLength: 255 description: >- 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. idempotencyKey: type: string minLength: 1 maxLength: 255 description: Stable key for safely retrying this create request. webhookUrl: type: string format: uri pattern: ^https:// description: >- 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. SmsConversationCreateResponse: allOf: - $ref: '#/components/schemas/ResponseEnvelope' - type: object properties: data: $ref: '#/components/schemas/SmsConversationCreated' AgentSelector: type: object description: >- Select exactly one agent. Use agentSlug for PAM-managed agents, or agentId for a specific custom agent. properties: agentId: type: string format: uuid description: Specific custom agent id. agentSlug: type: string minLength: 1 maxLength: 255 description: Stable slug for a PAM-managed agent. oneOf: - required: - agentId - required: - agentSlug E164PhoneNumber: type: string pattern: ^\+\d{7,15}$ description: Phone number in E.164 format. DynamicVariables: type: object additionalProperties: type: string description: >- Public string values used by the selected agent. PAM-managed recall, retention, and declined-services agents require the variables listed in the Agents guide. PAM may generate internal prompt context blocks from these values; generated context blocks are not returned by conversation GET or list responses. ResponseEnvelope: type: object properties: data: {} meta: $ref: '#/components/schemas/Meta' SmsConversationCreated: type: object required: - id - conversationId - providerMessageId - status properties: id: type: string format: uuid conversationId: type: string format: uuid providerMessageId: type: string description: Provider message id for the opening SMS. status: $ref: '#/components/schemas/ConversationStatus' ErrorResponse: type: object properties: error: type: object properties: code: type: string message: type: string details: description: Optional field-level validation details. nullable: true meta: $ref: '#/components/schemas/Meta' Meta: type: object properties: requestId: type: string ConversationStatus: type: string enum: - queued - in_progress - completed - failed - cancelled responses: ValidationError: description: Request validation failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Missing, expired, revoked, or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Conflict: description: Request conflicts with the current resource state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ServerError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerApiKey: type: http scheme: bearer description: 'API key provided as `Authorization: Bearer `.' x-default: pk_live_your_api_key ````