> ## Documentation Index > Fetch the complete documentation index at: https://help.wotnot.io/llms.txt > Use this file to discover all available pages before exploring further. # Create conversation > Starts a new conversation with a contact and sends the first message. What you send in the body depends on the channel: WhatsApp or SMS. ## OpenAPI ````yaml api-reference/create-conversation.json POST /v1/conversations openapi: 3.1.0 info: title: WotNot API version: 1.0.0 description: 'WotNot API: Create conversation.' servers: - url: https://api.wotnot.io description: Production security: - bearerAuth: [] paths: /v1/conversations: post: summary: Create conversation description: >- Starts a new conversation with a contact and sends the first message. What you send in the body depends on the channel: WhatsApp or SMS. operationId: createConversation requestBody: required: true description: >- The message to send. Its shape depends on the channel, so pick WhatsApp or SMS. content: application/json: schema: oneOf: - $ref: '#/components/schemas/WhatsAppConversationRequest' title: WhatsApp - $ref: '#/components/schemas/SmsConversationRequest' title: SMS examples: whatsapp: summary: WhatsApp value: channel: WHATSAPP from: '1123123123' to: phone: '11231231230' name: John Doe email: example@domain.com message: type: template data: template: test_template parameters: header: - John body: - Doe - Doe2 buttons: copy_code: '123456' otp: '123456' url: any variables: name: John Doe assignee: agent_email@domain.com sms: summary: SMS value: channel: SMS from: 1-123-1231230 to: phone: 1-1321231320 name: John Doe email: abc@acme.com message: type: text text: Hii assignee: agent_email@domain.com responses: '200': description: >- Returns `ok` set to `true`, the new `conversation`, and the `contact` it's with. content: application/json: schema: type: object required: - ok - conversation - contact properties: ok: type: boolean description: '`true` when the request worked. Errors return `false`.' example: true conversation: type: object description: The new conversation. required: - id - message_id - created_at - assignee properties: id: type: string description: The conversation's ID. example: 12wfegrgt4t message_id: type: string description: The ID of the message that was sent. example: sdvgret4353b created_at: type: string description: >- When the conversation was created. Empty (`""`) in the example. example: '' assignee: type: object description: The teammate the conversation is assigned to. required: - id - to properties: id: type: integer description: The teammate's user ID. example: 123 to: type: string description: The teammate's email address. example: agent_email@domain.com contact: type: object description: The contact the conversation is with. required: - id - name - phone - email properties: id: type: string description: The contact's ID. example: '11111111' name: type: string description: The contact's name. example: John Doe phone: type: string description: The contact's phone number. example: '1234567890' email: type: string description: The contact's email address. example: example@domain.com example: ok: true conversation: id: 12wfegrgt4t message_id: sdvgret4353b created_at: '' assignee: id: 123 to: agent_email@domain.com contact: id: '11111111' name: John Doe phone: '1234567890' email: example@domain.com '400': description: >- The conversation couldn't be created. The examples show the possible reasons, such as an expired channel token, a channel that isn't enabled, or a blocked contact. Check `error` to see which. content: application/json: schema: $ref: '#/components/schemas/CodedError' examples: channel_token_expired: summary: Channel token expired value: ok: false error: CHANNEL_TOKEN_EXPIRED code: CHANNEL_TOKEN_EXPIRED message: >- Token used to configure the channel is expired. Please reconfigure the channel. status: 400 creation_exception: summary: Try again later value: ok: false error: CONVERSATION_CREATION_EXCEPTION code: CONVERSATION_CREATION_EXCEPTION message: >- Conversation is not created. Please try again after some time. status: 400 channel_not_enabled: summary: Channel not enabled value: ok: false error: CHANNEL_NOT_ENABLED code: CHANNEL_NOT_ENABLED message: This channel is not enabled in the account. status: 400 contact_blocked: summary: Contact is blocked value: ok: false error: CONTACT_IS_BLOCKED code: CONTACT_IS_BLOCKED message: Conversation cannot be created for blocked contact. status: 400 user_limit: summary: User limit reached value: ok: false error: CONVERSATION_NOT_CREATED code: CONVERSATION_NOT_CREATED message: Conversation is not created due to user limit validation status: 400 '401': description: Your token is invalid. Check the `Authorization` header. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: JWT_SIGNATURE_EXCEPTION message: Invalid JWT token ok: false status: 401 '404': description: >- Something the request refers to wasn't found in your account: the `from` phone number or the WhatsApp template, or the template isn't approved. Check `error` to see which. content: application/json: schema: $ref: '#/components/schemas/CodedError' examples: from_not_configured: summary: Phone number not configured value: ok: false error: PHONE_NUMBER_IS_NOT_CONFIGURED code: PHONE_NUMBER_IS_NOT_CONFIGURED message: ’From’ phone number is not configured in the account. status: 404 template_not_found: summary: WhatsApp template not found value: ok: false error: WHATSAPP_TEMPLATE_NOT_FOUND code: WHATSAPP_TEMPLATE_NOT_FOUND message: WhatsApp template is not available in the account. status: 404 template_not_approved: summary: Template not approved value: ok: false error: TEMPLATE_NOT_APPROVED code: TEMPLATE_NOT_APPROVED message: Oops, template is not approved status: 404 components: schemas: WhatsAppConversationRequest: type: object title: WhatsApp description: Start a conversation on WhatsApp by sending a template message. required: - channel - from - to - message - assignee properties: channel: type: string enum: - WHATSAPP description: Set to `WHATSAPP`. example: WHATSAPP from: type: string description: >- The WhatsApp phone number to send from. It must be configured in your WotNot account. example: '1123123123' to: $ref: '#/components/schemas/ConversationRecipient' message: type: object description: The message to send. required: - type - data properties: type: type: string description: >- The kind of message, for example `template` to send a WhatsApp template. example: template data: type: object description: The template to send and the values to fill it with. required: - template - parameters - variables properties: template: type: string description: >- The name of the WhatsApp template to send, for example `test_template`. It must be in your account and approved. example: test_template parameters: type: object description: >- Values sent with the template for its header, body and buttons. required: - header - body properties: header: type: array description: >- Values for the placeholders in the template's header, for example `["John"]`. items: type: string body: type: array description: >- Values for the placeholders in the template's body, for example `["Doe", "Doe2"]`. items: type: string buttons: type: object description: Values for the template's buttons. required: - copy_code - otp - url properties: copy_code: type: string description: >- The code for a copy-code button, for example `123456`. example: '123456' otp: type: string description: >- The one-time password for an OTP button, for example `123456`. example: '123456' url: type: string description: The value for a URL button. example: any variables: type: object description: >- Variables, such as contact or conversation details, that get replaced with real values. required: - name properties: name: type: string description: A variable called `name`, for example `John Doe`. example: John Doe assignee: type: string description: The email address of the teammate to assign the conversation to. example: agent_email@domain.com SmsConversationRequest: type: object title: SMS description: Start a conversation by SMS with a text message. required: - channel - from - to - message - assignee properties: channel: type: string enum: - SMS description: Set to `SMS`. example: SMS from: type: string description: >- The phone number to send the SMS from. It must be configured in your WotNot account. example: 1-123-1231230 to: $ref: '#/components/schemas/ConversationRecipient' message: type: object description: The message to send. required: - type - text properties: type: type: string description: >- The kind of message, for example `text` for a plain text message. example: text text: type: string description: The message text. example: Hii assignee: type: string description: The email address of the teammate to assign the conversation to. example: agent_email@domain.com CodedError: type: object description: An error with a short code that says what went wrong. required: - ok - message - error - code properties: ok: type: boolean description: Always `false` when something went wrong. example: false message: type: string description: What went wrong, in plain words. example: Please reach out to support to use this feature error: type: string description: >- A short error code in capital letters, for example `UNAUTHORIZED_FEATURE`. Check this in your code to tell errors apart. example: UNAUTHORIZED_FEATURE code: type: string description: A code for the result. In these examples it matches `error`. example: UNAUTHORIZED_FEATURE status: type: integer description: >- The HTTP status code, repeated in the body. Not every error includes it. example: 401 Error: type: object description: Returned whenever a request fails. required: - error - ok - status - message properties: error: type: string description: >- A short error code in capital letters, for example `UNAUTHORIZED`. Check this in your code to tell errors apart. example: UNAUTHORIZED ok: type: boolean description: Always `false` when something went wrong. example: false status: type: integer description: The HTTP status code, repeated in the body, for example `401`. example: 401 message: type: string description: What went wrong and how to fix it, in plain words. example: Invalid token. Provide the valid account token. ConversationRecipient: type: object description: The contact to start the conversation with. required: - phone - name - email properties: phone: type: string description: The contact's phone number. example: '11231231230' name: type: string description: The contact's name. example: John Doe email: type: string description: The contact's email address. example: example@domain.com securitySchemes: bearerAuth: type: http scheme: bearer description: >- All of WotNot's APIs use Bearer token authentication. Send your account token as `Bearer `. You can find it in Settings > Account Settings > Developer. Keep it on your server: anyone who has it can call the API as your account. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.