---
updatedAt: 2026-05-04T07:02:55.000Z
agentTools:
  projectIndex: https://developers.intandem.tech/llms.txt
---

# Create a Business Communication Message

## Overview
Send a message to a business. Available for **Staff, App, and Directory tokens**.

**Note:** Sending messages requires a channel with `active` status. Channels are activated asynchronously via webhook callback from the communication-gw, not immediately upon creation. Ensure the channel has been activated before attempting to send messages.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Communication",
    "description": "Unified OpenAPI specification for communication domain",
    "version": "3.0",
    "x-generated": {
      "sourceFiles": [
        "business_phone_numbers.json",
        "contact_channels.json",
        "legacy_v1_communication.json",
        "communication.json",
        "activity_message.json",
        "communication.json",
        "conversations.json",
        "notification_template.json",
        "legacy_v2_communication.json",
        "staff_notification.json",
        "messages.json"
      ],
      "pathNormalizations": [
        {
          "file": "legacy_v1_communication.json",
          "basePath": "/platform/v1",
          "transformations": [
            {
              "original": "/conversations",
              "normalized": "/platform/v1/conversations",
              "basePath": "/platform/v1"
            },
            {
              "original": "/clients/{client_id}/conversations",
              "normalized": "/platform/v1/clients/{client_id}/conversations",
              "basePath": "/platform/v1"
            },
            {
              "original": "/messages",
              "normalized": "/platform/v1/messages",
              "basePath": "/platform/v1"
            },
            {
              "original": "/numbers/dedicated_numbers/assign",
              "normalized": "/platform/v1/numbers/dedicated_numbers/assign",
              "basePath": "/platform/v1"
            },
            {
              "original": "/numbers/dedicated_numbers/set_two_way_texting_status",
              "normalized": "/platform/v1/numbers/dedicated_numbers/set_two_way_texting_status",
              "basePath": "/platform/v1"
            },
            {
              "original": "/numbers/twilio",
              "normalized": "/platform/v1/numbers/twilio",
              "basePath": "/platform/v1"
            },
            {
              "original": "/numbers/twilio/{sub_account_id}",
              "normalized": "/platform/v1/numbers/twilio/{sub_account_id}",
              "basePath": "/platform/v1"
            }
          ]
        },
        {
          "file": "communication.json",
          "basePath": "/business/communication",
          "transformations": [
            {
              "original": "/channels",
              "normalized": "/business/communication/channels",
              "basePath": "/business/communication"
            },
            {
              "original": "/channels/{uid}",
              "normalized": "/business/communication/channels/{uid}",
              "basePath": "/business/communication"
            },
            {
              "original": "/messages",
              "normalized": "/business/communication/messages",
              "basePath": "/business/communication"
            },
            {
              "original": "/messages/{messageUid}",
              "normalized": "/business/communication/messages/{messageUid}",
              "basePath": "/business/communication"
            },
            {
              "original": "/sessions",
              "normalized": "/business/communication/sessions",
              "basePath": "/business/communication"
            },
            {
              "original": "/sessions/typing",
              "normalized": "/business/communication/sessions/typing",
              "basePath": "/business/communication"
            },
            {
              "original": "/sessions/{uid}",
              "normalized": "/business/communication/sessions/{uid}",
              "basePath": "/business/communication"
            }
          ]
        },
        {
          "file": "conversations.json",
          "basePath": "/v2",
          "transformations": [
            {
              "original": "/conversations/{id}",
              "normalized": "/v2/conversations/{id}",
              "basePath": "/v2"
            }
          ]
        },
        {
          "file": "legacy_v2_communication.json",
          "basePath": "/v2",
          "transformations": [
            {
              "original": "/conversations/{conversation_id}/messages",
              "normalized": "/v2/conversations/{conversation_id}/messages",
              "basePath": "/v2"
            }
          ]
        },
        {
          "file": "messages.json",
          "basePath": "/business/messaging",
          "transformations": [
            {
              "original": "/v1/channels",
              "normalized": "/business/messaging/v1/channels",
              "basePath": "/business/messaging"
            },
            {
              "original": "/v1/channels/typing",
              "normalized": "/business/messaging/v1/channels/typing",
              "basePath": "/business/messaging"
            }
          ]
        }
      ],
      "pathConflicts": [],
      "componentConflicts": [
        {
          "type": "schema",
          "name": "ErrorResponse",
          "resolution": "Renamed to ErrorResponse_contact_channels",
          "files": [
            "merged",
            "contact_channels.json"
          ]
        },
        {
          "type": "schema",
          "name": "ErrorResponse",
          "resolution": "Renamed to ErrorResponse_communication",
          "files": [
            "merged",
            "communication.json"
          ]
        },
        {
          "type": "schema",
          "name": "Response",
          "resolution": "Renamed to Response_communication",
          "files": [
            "merged",
            "communication.json"
          ]
        },
        {
          "type": "schema",
          "name": "ErrorResponse",
          "resolution": "Renamed to ErrorResponse_activity_message",
          "files": [
            "merged",
            "activity_message.json"
          ]
        },
        {
          "type": "schema",
          "name": "Response",
          "resolution": "Renamed to Response_communication",
          "files": [
            "merged",
            "communication.json"
          ]
        },
        {
          "type": "schema",
          "name": "ErrorResponse",
          "resolution": "Renamed to ErrorResponse_conversations",
          "files": [
            "merged",
            "conversations.json"
          ]
        }
      ],
      "totalPaths": 35,
      "totalComponents": 43
    }
  },
  "servers": [
    {
      "url": "https://api.vcita.biz",
      "description": "Unified API Gateway server"
    }
  ],
  "paths": {
    "/business/communication/messages": {
      "post": {
        "description": "## Overview\nSend a message to a business. Available for **Staff, App, and Directory tokens**.\n\n**Note:** Sending messages requires a channel with `active` status. Channels are activated asynchronously via webhook callback from the communication-gw, not immediately upon creation. Ensure the channel has been activated before attempting to send messages.",
        "operationId": "MessagesController_createMessage",
        "parameters": [],
        "responses": {
          "201": {
            "description": "Message sent successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Response"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/MessageResponseDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized to perform action.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "summary": "Create a Business Communication Message",
        "tags": [
          "Communication Messages (SMS)"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateMessageDto"
              }
            }
          }
        },
        "security": [
          {
            "Bearer": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Response": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string",
                  "description": "The field that caused the error (for validation errors)"
                },
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "code",
                "message"
              ]
            }
          }
        },
        "required": [
          "success",
          "errors"
        ],
        "example": {
          "success": false,
          "errors": [
            {
              "field": "verification_request_data.postal_code",
              "code": "INVALID_FORMAT",
              "message": "Must be exactly 5 digits for US addresses"
            },
            {
              "field": "verification_request_data.state",
              "code": "INVALID_FORMAT",
              "message": "Must be a valid 2-letter state code"
            }
          ]
        }
      },
      "CreateMessageDto": {
        "properties": {
          "attachments": {
            "description": "Message attachments",
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "channel_uid": {
            "description": "Channel uid. 36 chars uuid.",
            "type": "string"
          },
          "contact_uid": {
            "description": "Contact Uid",
            "type": "string"
          },
          "contact_data": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Optional channel-provided contact metadata for AI Chat Receptionist context, such as contact_name, email, phone, or other scalar contact details. This object is metadata only: it does not participate in routing or session lookup, and contact_uid/external_uid remain the routing identifiers. When provided on an intercepted inbound message without contact_uid, communication-gw forwards it to the AI receptionist as unverified client context and does not include it in the normal CRM fallback message payload.",
            "example": {
              "contact_name": "Itzik Levy",
              "email": "itzik@example.com",
              "phone": "+15551234567",
              "company": "Acme"
            },
            "type": "object"
          },
          "created_at": {
            "description": "Message creation date time [optional | Format: YYYY-MM-DD HH:MM:SS].",
            "type": "string"
          },
          "direction": {
            "description": "Message Direction.",
            "enum": [
              "client_to_business",
              "business_to_client"
            ],
            "type": "string"
          },
          "external_uid": {
            "description": "Paired contact code.",
            "type": "string"
          },
          "message": {
            "description": "Message content.",
            "type": "string"
          },
          "message_uid": {
            "description": "Message uid. Max 255 chars identifier. vCita will send message status updates based on this identifier.Must be unique per channel.",
            "type": "string"
          }
        },
        "required": [
          "external_uid",
          "message",
          "message_uid",
          "channel_uid"
        ],
        "type": "object"
      },
      "MessageResponseDto": {
        "properties": {
          "message": {
            "$ref": "#/components/schemas/MessageResponseEntity"
          }
        },
        "required": [
          "message"
        ],
        "type": "object"
      },
      "MessageResponseEntity": {
        "properties": {
          "status": {
            "description": "Message status. Enum MessageStatus.",
            "enum": [
              "pending",
              "channel_pending",
              "sent",
              "received",
              "read",
              "error",
              "unavailable"
            ],
            "type": "string"
          },
          "uid": {
            "description": "Message uid",
            "type": "string"
          }
        },
        "required": [
          "uid",
          "status"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "Bearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Provide a valid bearer token in the Authorization header. Example: 'Authorization: Bearer {app_token}'"
      }
    }
  },
  "tags": [
    {
      "description": "Nexmo-based communication gateway endpoints for SMS/messaging channels. These endpoints follow an async webhook-based lifecycle: channels and sessions start as 'pending' and are activated asynchronously via webhook callbacks from the communication-gw to the calling application. A webhook listener is required to receive activation events.",
      "name": "Communication Messages (SMS)"
    }
  ]
}
```