Breadcrumbs

Envio de Mensagens

Esta página é para quando você quer mandar uma mensagem nova para o cliente dentro de um atendimento seja um texto de chat, um WhatsApp com modelo pronto, um e-mail, um SMS ou até só um "está digitando..." Todos os endpoints aqui partem de um caso já existente.

Todas as requisições exigem o cabeçalho Authorization veja Autenticação e Segurança se ainda não souber como conseguir e usar o token.

Se o que você precisa é consultar o que já foi trocado com o cliente (histórico de conversa, conteúdo de e-mail, anexos, gravações de voz), isso fica em Canais e Mensagens, não aqui.

Índice desta página

Enviar mensagem no canal de chat ativo (v1)

As quatro variações abaixo (texto, solicitação de localização, botões e botões interativos) usam o mesmo endpoint, diferenciadas pelo conteúdo do campo payload. O canal de chat ativo por último ou que recebeu a última mensagem é o escolhido automaticamente para o envio. Canais possíveis: WhatsApp, Webchat, Instagram, Messenger e Telegram, desde que o caseId esteja ativo.

Request 

POST https://api.cvortex.com/v1/message/chat/send

Header: Authorization

O corpo é enviado como multipart/form-data, com um campo payload (texto/JSON) e, opcionalmente, um campo file (arquivo).

Campo

Tipo

Content-Type

Obrigatório

Descrição

payload

text (JSON)

application/json

Sim

Ver estrutura por variação abaixo

file

file

Auto

Não

Arquivo a enviar junto com a mensagem (jpg, pdf, doc, docx)

Texto

payload contém message, caseId e, opcionalmente, fileUrl (URL de imagem/arquivo a enviar use fileUrl ou o campo file, nunca os dois).

message: Conteúdo da mensagem de texto.
caseId: Identificador do caso (atendimento).
fileUrl: URL de uma imagem ou arquivo que será enviado ao contato.

Exemplo 

curl --location 'https://api.cvortex.com/v1/message/chat/send' \
  --header 'Authorization: Bearer {token}' \
  --form 'payload="{\"message\": \"Olá tudo bem!\", \"caseId\": \"3273\"}";type=application/json'

Response

JSON
{
  "identifier": "e887f7f1-3cdd-4b01-bc3a-5421d29d153a"
}

Solicitar localização (WhatsApp)

payload contém message, caseId e messageType: "LOCATION_REQUEST".

message: Conteúdo da mensagem de texto.
caseId: Identificador do caso (atendimento).
messageType: "LOCATION_REQUEST" indica o envio de uma mensagem de solicitação de localização.

Exemplo 

curl --location 'https://api.cvortex.com/v1/message/chat/send' \
  --header 'Authorization: Bearer {token}' \
  --form 'payload="{\"message\": \"Olá, me envia sua localização por favor.\", \"caseId\": \"3305\", \"messageType\": \"LOCATION_REQUEST\"}";type=application/json'

Botões (WhatsApp)

payload contém message, caseId e action (lista de opções limite de 10 botões). Os campos headerAction e footerAction são opcionais.

Estrutura de cada item de action:

JSON
{
  "payload": "opção 1",
  "text": "opção 1",
  "type": "reply",
  "description": "Descrição 1"
}

Exemplo 

curl --location 'https://api.cvortex.com/v1/message/chat/send' \
  --header 'Authorization: Bearer {token}' \
  --form 'payload="{\"message\": \"Outra imagem\", \"caseId\": \"3305\", \"actions\": [{\"payload\": \"opção 1\", \"text\": \"opção 1\", \"type\": \"reply\", \"description\": \"Descrição 1\"}, {\"payload\": \"opção 2\", \"text\": \"opção 2\", \"type\": \"reply\", \"description\": \"Descrição 2\"}, {\"payload\": \"opção 3\", \"text\": \"opção 3\", \"type\": \"reply\", \"description\": \"Descrição 3\"}, {\"payload\": \"opção 4\", \"text\": \"opção 4\", \"type\": \"reply\", \"description\": \"Descrição 4\"}]}";type=application/json'

Botões interativos, com imagem (WhatsApp)

Igual ao anterior, mas com fileUrl (imagem/arquivo) e limite de 3 botões.

Exemplo 

curl --location 'https://api.cvortex.com/v1/message/chat/send' \
  --header 'Authorization: Bearer {token}' \
  --form 'payload="{\"message\": \"Outra imagem\", \"caseId\": \"3305\", \"fileUrl\":\"https://exemplo.com/imagem.png\", \"actions\": [{\"payload\": \"opção 1\", \"text\": \"opção 1\", \"type\": \"reply\", \"description\": \"Descrição 1\"}, {\"payload\": \"opção 2\", \"text\": \"opção 2\", \"type\": \"reply\", \"description\": \"Descrição 2\"}]}";type=application/json'

Enviar mensagem no canal de chat ativo (v2)

Endpoint mais novo para enviar mensagens, com suporte a um tipo de conteúdo mais rico que a v1 abaixo: mensagem de pagamento (com boleto e Pix). A diferença técnica principal é que aqui o corpo é enviado como JSON puro (Content-Type: application/json), e não como multipart/form-data como na v1.

Request 

POST https://api.cvortex.com/v2/message/chat/send

Header: Authorization, Content-Type: application/json

Campos comuns a qualquer tipo de mensagem v2

Campo

Tipo

Obrigatório

Descrição

caseId

string

Sim

Identificador do caso (atendimento)

providerAccountKeyId

string

Sim

Conta do provedor de WhatsApp usada para o envio

message

string

Não

Texto que acompanha o conteúdo especial (aceita quebra de linha com \n)

O tipo da mensagem é definido por qual campo extra você inclui no corpo, além dos três acima:

Campo extra incluído

Tipo de mensagem resultante

nenhum (só message)

Texto simples

fileUrl

Arquivo / imagem

actions

Botões (até 3 itens) ou lista (mais de 3 itens)

payment

Pagamento boleto / Pix

Texto (v2)

Mensagem de texto simples: basta enviar os três campos comuns, sem nenhum campo extra.

Exemplo

JSON
{
  "caseId": "44657",
  "providerAccountKeyId": "486b5be8-8748-4fe9-9aaa-b1adec2f67ee",
  "message": "Teste"
}

Arquivo / Imagem (WhatsApp)

Envia um arquivo ou imagem através do campo extra fileUrl funciona de forma parecida com o fileUrl já visto na v1.

Campo

Tipo

Descrição

fileUrl

string

URL pública do arquivo ou imagem a ser enviado

Exemplo

JSON
{
  "caseId": "44657",
  "providerAccountKeyId": "486b5be8-8748-4fe9-9aaa-b1adec2f67ee",
  "fileUrl": "https://exemplo.com/arquivos/imagem.jpg"
}

Botões / Lista de opções (WhatsApp)

Envia uma mensagem com opções de resposta rápida, através do campo extra actions. A quantidade de itens em actions decide como a mensagem aparece pro cliente:

Quantidade de itens em actions

Como aparece no WhatsApp

Até 3

Botões

Mais de 3

Lista

Campo

Tipo

Descrição

actions

array

Opções apresentadas ao cliente até 3 viram botões, mais de 3 viram lista

actions[].type

string

Tipo da opção no exemplo, sempre reply

actions[].payload

string

Valor interno da opção (o que volta quando o cliente escolhe)

actions[].text

string

Texto da opção, exibido ao cliente

Exemplo mais de 3 itens (vira lista)

JSON
{
  "caseId": "44657",
  "providerAccountKeyId": "486b5be8-8748-4fe9-9aaa-b1adec2f67ee",
  "message": "Agora, escolha o seu *banco* na lista de parceiros.",
  "actions": [
    { "type": "reply", "payload": "1", "text": "Banco Bradesco" },
    { "type": "reply", "payload": "2", "text": "Banco do Brasil" },
    { "type": "reply", "payload": "3", "text": "Banco Itau S/A" },
    { "type": "reply", "payload": "4", "text": "Banco Santander" },
    { "type": "reply", "payload": "5", "text": "Banrisul" },
    { "type": "reply", "payload": "6", "text": "Nubank" },
    { "type": "reply", "payload": "7", "text": "Nenhum desses bancos" }
  ]
}

Exemplo até 3 itens (vira botões)

JSON
{
  "caseId": "44657",
  "providerAccountKeyId": "486b5be8-8748-4fe9-9aaa-b1adec2f67ee",
  "message": "Confirma o cancelamento do seu pedido?",
  "actions": [
    { "type": "reply", "payload": "1", "text": "Sim, cancelar" },
    { "type": "reply", "payload": "2", "text": "Não, manter pedido" }
  ]
}

Pagamento boleto / Pix (WhatsApp)

Envia, no WhatsApp, um cartão de cobrança com o resumo do pedido e um ou mais botões de pagamento (por exemplo, "copiar código Pix" e "copiar linha digitável do boleto").

O campo extra que ativa esse tipo é payment:

Campo

Tipo

Descrição

payment.currency

string

Moeda da cobrança (ex: BRL)

payment.header

object

Cabeçalho visual do cartão de pagamento

payment.header.type

string

Tipo de cabeçalho no exemplo, document

payment.header.document

object

Presente quando header.type é document

payment.header.document.link

string

URL pública do arquivo mostrado no cabeçalho (ex: PDF da fatura)

payment.header.document.filename

string

Nome do arquivo exibido ao cliente

payment.order

object

Detalhes do pedido/cobrança

payment.order.items

array

Itens da cobrança

payment.order.items[].name

string

Descrição do item

payment.order.items[].quantity

number

Quantidade

payment.order.items[].retailerId

string

Código interno do item/produto no seu sistema

payment.order.items[].amount

object

Valor do item ver "Como funciona value/offset" abaixo

payment.order.status

string

Status do pedido (ex: pending)

payment.order.subtotal

object

Subtotal do pedido (mesma estrutura de amount)

payment.order.tax

object

Valor de imposto/taxa (mesma estrutura de amount; 0 se não houver)

payment.paymentSettings

array

Formas de pagamento oferecidas ao cliente pode ter mais de uma

payment.paymentSettings[].type

string

Identifica a forma de pagamento daquele item: pix_dynamic_code ou boleto

payment.paymentSettings[].pixDynamicCode

object

Presente quando type é pix_dynamic_code

payment.paymentSettings[].pixDynamicCode.code

string

Código Pix "copia e cola"

payment.paymentSettings[].pixDynamicCode.key

string

Chave Pix do recebedor

payment.paymentSettings[].pixDynamicCode.keyType

string

Tipo da chave Pix (ex: EMAIL)

payment.paymentSettings[].pixDynamicCode.merchantName

string

Nome do recebedor, exibido ao cliente

payment.paymentSettings[].boleto

object

Presente quando type é boleto

payment.paymentSettings[].boleto.digitableLine

string

Linha digitável do boleto (o número por trás do botão "copiar código de barras")

payment.paymentType

string

País/modelo de pagamento no exemplo, br

payment.referenceId

string

Identificador do pedido/cobrança no seu sistema

payment.totalAmount

object

Valor total cobrado (mesma estrutura de amount)

payment.type

string

Tipo do pedido dentro do pagamento no exemplo, digital-goods

Como funciona value/offset: todo valor monetário (amount, subtotal, tax, totalAmount) vem como { "value": número, "offset": número }. O valor real é value ÷ offset. No exemplo abaixo, value: 5000 e offset: 100 resultam em R$ 50,00 que bate com o "Valor: R$50,00" escrito no texto da mensagem.

Exemplo

Bash
curl --location 'https://api.cvortex.com/v2/message/chat/send' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "caseId": "44608",
    "providerAccountKeyId": "486b5be8-8748-4fe9-9aaa-b1adec2f67ee",
    "message": "Certo. Aqui está o resumo da sua conta:\n\nInternet do CEP: 00000-000\nVencimento: 18/01/21\nValor: R$50,00",
    "payment": {
        "currency": "BRL",
        "header": {
            "type": "document",
            "document": {
                "link": "https://exemplo.com/arquivos/fatura.pdf",
                "filename": "fatura.pdf"
            }
        },
        "order": {
            "items": [
                {
                    "amount": { "offset": 100, "value": 5000 },
                    "name": "Internet do CEP: 00000-000",
                    "quantity": 1,
                    "retailerId": "PLANO-FIBRA-012021"
                }
            ],
            "status": "pending",
            "subtotal": { "offset": 100, "value": 5000 },
            "tax": { "offset": 100, "value": 0 }
        },
        "paymentSettings": [
            {
                "pixDynamicCode": {
                    "code": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000",
                    "key": "pagamentos@empresas.com",
                    "keyType": "EMAIL",
                    "merchantName": "Empresa Exemplo Ltda"
                },
                "type": "pix_dynamic_code"
            },
            {
                "type": "boleto",
                "boleto": {
                    "digitableLine": "00000000000000000000000000000000000000000000000"
                }
            }
        ],
        "paymentType": "br",
        "referenceId": "PED-20260605-0042",
        "totalAmount": { "offset": 100, "value": 5000 },
        "type": "digital-goods"
    }
}'

Flow (WhatsApp)

Abre um formulário interativo (Flow) já cadastrado na conta do WhatsApp Business, para o cliente preencher dentro da própria conversa.

Campo

Tipo

Descrição

assetId

string

ID Hash do atendimento

body

string

Texto principal da mensagem

header

string

Texto do cabeçalho da mensagem

flow.flowAction

string

Ação do Flow no exemplo, navigate

flow.flowCTA

string

Texto do botão que abre o Flow

flow.flowToken

string

Token de contexto do Flow no exemplo, carrega idcaso e cpf codificados como texto

flow.flowId

string

ID do Flow cadastrado na conta do WhatsApp Business

flow.flowScreen

string

Tela inicial do Flow a ser aberta

flow.flowScreenData

object

Dados usados para pré-preencher a tela inicial do Flow

Exemplo

JSON
{
  "assetId": "7bb33ad4-43ab-4c72-9044-d076539bed7d",
  "body": "Clique no botão abaixo para confirmar o seu produto:",
  "flow": {
    "flowAction": "navigate",
    "flowCTA": "Ver meus produtos",
    "flowToken": "idcaso=12345;cpf=01234567889",
    "flowId": "123456789012345",
    "flowScreen": "CONFIRMAR_DOCUMENTO",
    "flowScreenData": {
      "cpf": "01234567889"
    }
  },
  "header": "Empresa"
}

Enviar HSM WhatsApp (Template)

Envia um Highly Structured Message (Template), usado no WhatsApp, para iniciar conversas fora da janela de 24 horas.

Request 

POST https://api.cvortex.com/v1/message/chat/hsm/send

Header: Authorization

Parâmetros de body

Campo

Tipo

Obrigatório

Descrição

caseId

string

Sim

Identificador do caso (atendimento)

templateId

string

Sim

ID do template pré-aprovado

to

string

Sim

Número do destinatário (ex: +5534999999999)

templateNamespace

string

Sim

Namespace do provedor do template

providerAccountKeyId

string

Sim

Identificador da conta do provedor (ex: Twilio, Meta)

templateArgs

string[]

Não

Argumentos variáveis para preencher o template

Exemplo

JSON
{
  "caseId": "123",
  "templateId": "welcome_tpl",
  "to": "+5534999999999",
  "templateNamespace": "namespace_example",
  "providerAccountKeyId": "prov-1",
  "templateArgs": ["Nome", "Suporte XPTO"]
}

O templateId usado acima precisa já existir e estar aprovado veja como cadastrar e consultar templates logo abaixo.

Atualizar template de WhatsApp

Permite atualizar as configurações de um template de WhatsApp, como categoria, template de fallback (o modelo alternativo usado quando o principal falha) e validações.

Request 

PUT https://api.cvortex.com/v1/whatsapp/templates

Header: Authorization

Parâmetros de body

Campo

Tipo

Descrição

Obrigatório

desiredCategory

string

Categoria desejada para o template

Sim

fallbackTemplate

string

Nome ou identificador do template de reserva (fallback)

Sim

isFallbackTemplate

boolean

Define se este template é um template de fallback

Sim

language

string

Código do idioma do template (ex: pt_BR)

Sim

providerAccountId

string

Identificador da conta no provedor

Sim

removeFallbackTemplate

boolean

Se verdadeiro, remove o template de fallback associado

Sim

templateId

string

Identificador único do template

Sim

validateDesiredCategory

boolean

Se verdadeiro, valida a categoria selecionada

Sim

Exemplo de Payload

JSON
{
  "desiredCategory": "string",
  "fallbackTemplate": "string",
  "isFallbackTemplate": true,
  "language": "string",
  "providerAccountId": "string",
  "removeFallbackTemplate": true,
  "templateId": "string",
  "validateDesiredCategory": true
}

Responses

Código

Descrição

200

Sucesso na atualização. Retorna o objeto do template atualizado, com detalhes de auditoria (createdAt, updatedAt) e status de sincronização.

201

Recurso criado com sucesso

401

Token de autorização ausente ou inválido

403

Sem permissão para acessar este recurso

404

Template não encontrado
JSON
{
  "active": true,
  "businessUnit": "string",
  "category": "string",
  "createdAt": 0,
  "createdBy": "string",
  "deleted": true,
  "desiredCategory": "string",
  "fallbackTemplate": "string",
  "id": "string",
  "isFallbackTemplate": true,
  "language": "string",
  "namespace": "string",
  "newCategory": "string",
  "phone": "string",
  "providerAccount": "string",
  "score": "string",
  "status": "string",
  "syncWitMeta": true,
  "templateId": "string",
  "templatePreview": "string",
  "templateType": "string",
  "tenantId": "string",
  "updatedAt": 0,
  "updatedBy": "string",
  "updatedCategory": true,
  "updatedCategoryAt": 0,
  "validateDesiredCategory": true,
  "version": "string"
}

Consultar templates de WhatsApp

Permite buscar e filtrar templates de WhatsApp existentes usando critérios como categoria, status, idioma e unidade de negócio.

Request 

GET https://api.cvortex.com/v1/whatsapp/templates/search

Header: Authorization

Parâmetros de URI

Campo

Tipo

Descrição

Obrigatório

businessUnit

string

Identificador da unidade de negócio

Não

category

string

Categoria atual do template (ex: MARKETING)

Não

desiredCategory

string

Categoria desejada para o template

Não

status

string

Status do template (ex: APPROVED)

Não

language

string

Código do idioma (ex: pt_BR)

Não

phone

string

Número de telefone associado

Não

limit

integer

Limite de resultados por página

Não

Exemplo 

GET https://api.cvortex.com/v1/whatsapp/templates/search?businessUnit=c81a4adb-7dee-4cc4-b24c-008de39e949a&category=MARKETING&desiredCategory=UTILITY&fallbackTemplate=1512a78d-dc32-4eb2-80b2-039bb577d01f&isFallbackTemplate=false&hasFallbackTemplate=true&language=pt_BR&namespace=ede088be_723f_4247_919a_dff5b910367b&phone=5534999999999&providerAccountId=b66c6352-b582-4ca1-b53d-05bf0a980bf7&status=APPROVED&templateId=cvortexwebhook&validateDesiredCategory=true&updatedCategory=false&limit=300

Response

JSON
[
  {
    "active": true,
    "businessUnit": "string",
    "category": "string",
    "createdAt": 0,
    "createdBy": "string",
    "deleted": true,
    "desiredCategory": "string",
    "fallbackTemplate": "string",
    "id": "string",
    "isFallbackTemplate": true,
    "language": "string",
    "namespace": "string",
    "newCategory": "string",
    "phone": "string",
    "providerAccount": "string",
    "score": "string",
    "status": "string",
    "syncWitMeta": true,
    "templateId": "string",
    "templatePreview": "string",
    "templateType": "string",
    "tenantId": "string",
    "updatedAt": 0,
    "updatedBy": "string",
    "updatedCategory": true,
    "updatedCategoryAt": 0,
    "validateDesiredCategory": true,
    "version": "string"
  }
]

Enviar mensagem com CTA (WhatsApp)

Envia uma mensagem do tipo CTA (call-to-action, com botão de link) para um caso com canal de WhatsApp ativo.

Request 

POST https://api.cvortex.com/v1/case/send-message-cta

Header: Authorization

Parâmetros de body

Nome

Tipo

Descrição

Obrigatório

assetId

string

ID Hash do atendimento

Sim

body

string

Texto do corpo da mensagem (máx. 1.024 caracteres)

Sim

buttonText

string

Texto do botão CTA (máx. 20 caracteres)

Sim

buttonURL

string

URL para onde o cliente será direcionado

Sim

footer

string

Texto do rodapé da mensagem (máx. 60 caracteres)

Sim

header

string

Texto do cabeçalho da mensagem (máx. 60 caracteres)

Sim

Exemplo

JSON
{
  "assetId": "95b5f027-0ae8-4ac5-88e5-9042b2003bf2",
  "body": "Agora, para fazer seu pedido, basta acessar o nosso portal de pedidos através do botão abaixo. Clique para acessar.",
  "buttonText": "Acessar Pedidos",
  "buttonURL": "https://exemplo.com/pedidos",
  "footer": "",
  "header": "Perfeito! Localização confirmada com sucesso"
}

Enviar e-mail com anexos

Envia um e-mail com ou sem anexos. O campo subject é obrigatório.

Request 

POST https://api.cvortex.com/v1/message/email/send

Header: Authorization

Parâmetros de body

Campo

Tipo

Obrigatório

Descrição

caseId

string

Sim

Identificador do caso (atendimento)

message

string

Sim

Corpo do e-mail (HTML ou texto)

subject

string

Sim

Assunto do e-mail

providerAccountKeyId

string

Sim

Conta do provedor de e-mail a ser utilizada

to

string[]

Sim

Lista de destinatários

conversationId

string

Não

ID da conversa (para respostas em thread)

digitalId

string

Não

ID digital para rastreamento

attachments (file)

file

Não

Arquivo a enviar junto com a mensagem (jpg, pdf, doc, docx)

Exemplo

JSON
{
  "message": "Olá",
  "subject": "Teste",
  "providerAccountKeyId": "mail-01",
  "to": ["email@empresas.com"],
  "caseId": "55"
}

O material de origem também trazia um exemplo mais completo, com corpo em HTML:

HTML
{
  "message": "<!doctype html><html><body><h2>Boas-vindas!</h2><p>Obrigado por testar nosso e-mail em HTML.</p><a href='https://exemplo.com'>Visitar</a></body></html>",
  "caseId": "283201",
  "subject": "Teste Envio Email External",
  "providerAccountKeyId": "5a4a23ed-bde7-41c3-8655-061ad3d9d4de",
  "to": ["email@empresas.com"]
}

Enviar SMS

Envia uma mensagem de texto simples (SMS) para um número de telefone.

Request 

POST https://api.cvortex.com/v1/message/sms/send

Header: Authorization

Parâmetros de body

Campo

Tipo

Obrigatório

Descrição

providerAccountKeyId

string

Sim

Conta do provedor de SMS

to

string

Sim

Número do destinatário (ex: +5534999999999)

message

string

Sim

Conteúdo da mensagem

caseId

string

Sim

Identificador do caso (atendimento)

Exemplo

JSON
{
  "providerAccountKeyId": "sms-provider",
  "to": "+5534999999999",
  "message": "Seu atendimento foi atualizado.",
  "caseId": "789"
}

Response

JSON
{
  "status": "SUCCESS",
  "messageId": "a1b2c3d4",
  "details": "Message queued successfully"
}

Enviar sinalização de "digitando" (WhatsApp)

Permite enviar a sinalização de lido e de "está digitando uma resposta" ao cliente.

Disponível apenas para WhatsApp via 360Dialog.

Request 

POST https://api.cvortex.com/v1/message/chat/read

Header: Authorization

Parâmetros de body

Campo

Tipo

Obrigatório

Descrição

messageId

string

Sim

ID da messageHistory recebida do cliente

sendTyping

boolean

Sim

true sinaliza que a mensagem está sendo digitada

Exemplo

JSON
{
  "messageId": "87d3dd5c-2c8e-4212-b2ba-5380c585fdea",
  "sendTyping": true
}