Breadcrumbs

Integrações de Anúncios (Meta e TikTok)

Quando alguém clica num anúncio do tipo "Clique para conversar no WhatsApp" (Click to WhatsApp) e vira um lead, Meta (dona do Facebook/Instagram) e TikTok querem saber o que aconteceu depois se virou venda, por exemplo para melhorar a entrega dos próprios anúncios. Esta página explica como avisar essas duas plataformas sobre a evolução de um lead que veio de um anúncio, usando dados do atendimento feito pela cVortex.

Todas as requisições exigem o cabeçalho Authorization vejaAutenticação e Segurançase ainda não souber como conseguir e usar o token.

Índice desta página

Enviar evento de funil para Leads Meta

Envia eventos de evolução do lead no funil diretamente para a Meta, enriquecendo cada evento com dados do atendimento, do canal de mensageria e dos identificadores do lead. Isso ajuda a Meta a reconhecer as etapas percorridas pelo lead, melhorar a atribuição das conversões e otimizar campanhas.

Request 

POST https://api.cvortex.com/v1/ads/meta/events/track

Header: Authorization

Parâmetros de body

Campo

Tipo

Obrigatório

Descrição

data

array

Sim

Lista de um ou mais eventos de funil enviados para a Meta

data[].action_source

string

Sim

Origem da ação que gerou o evento (correspondente ao canal usado)

data[].custom_data

object

Não

Dados adicionais da conversão (moeda, valor)

data[].custom_data.currency

string

Não

Moeda usada no valor da conversão (ex: BRL)

data[].custom_data.value

number

Não

Valor monetário associado ao evento de conversão

data[].event_name

string

Sim

Nome do evento enviado para a Meta (etapa do funil ou conversão)

data[].event_time

number

Sim

Data/hora do evento em timestamp Unix (segundos)

data[].messaging_channel

string

Sim

Canal de mensageria relacionado ao evento (ex: WhatsApp)

data[].user_data

object

Sim

Identificadores do usuário/lead usados pela Meta para atribuição

data[].user_data.ctwa_clid

string

Sim

Click ID do anúncio Click to WhatsApp, usado para relacionar o lead ao evento

data[].user_data.whatsapp_business_account_id

string

Sim

Identificador da conta WhatsApp Business associada ao atendimento/campanha

partner_agent

string

Sim

Nome do parceiro ou agente responsável pelo envio do evento

caseid

string

Sim

ID Hash do caso

Exemplo

JSON
{
  "data": [
    {
      "action_source": "string",
      "custom_data": {
        "currency": "string",
        "value": 0
      },
      "event_name": "string",
      "event_time": 0,
      "messaging_channel": "string",
      "user_data": {
        "ctwa_clid": "string",
        "whatsapp_business_account_id": "string"
      }
    }
  ],
  "partner_agent": "string",
  "caseid": "2834-asd-5-325-24-"
}

Enviar eventos de funil para Leads TikTok (CTWA para WhatsApp)

Envia ao TikTok os eventos de funil de um lead que chegou pelo WhatsApp a partir de um anúncio de mensagem do TikTok. Com isso, o TikTok atribui a conversão à campanha de origem.

O cVortex verifica se o caso está aberto e repassa o payload ao TikTok exatamente como foi recebido, sem validar nem completar campos. Por isso, o sistema que faz a chamada é responsável por enviar todos os campos no formato correto, inclusive o hash dos dados do usuário.

Atenção: a resposta 200 indica apenas que o evento foi repassado ao TikTok. Ela não confirma que o evento foi aceito ou atribuído. O TikTok também retorna 200 para eventos inválidos. Confira o recebimento no Events Manager do TikTok.

Request 

POST https://api.cvortex.com/v1/ads/tiktok/events/track

Header: Authorization

Parâmetros de body

Campo

Type

Value

Obrigatório

Descrição

event_source

string

"crm"


Origem do evento.

event_source_id

string

"7123456789012345678"


ID da fonte de eventos no TikTok.

partner_name

string

"cvortex"


Nome do parceiro da integração. Use cvortex.

messaging_channel

string

"whatsapp"


Canal da conversa. Use whatsapp.

assetId

string

"1234567890"



data[].event

string

"CompletePayment"

Sim

Nome do evento. Informe um dos valores listados em Eventos aceitos.

data[].event_time

integer

1790380800

Sim

Momento do evento, em Unix timestamp (segundos).

data[].event_id

string

"9f8b7c6d-..."

Recomendado

ID único do evento. Reenviar o mesmo ID evita conversões duplicadas.

data[].limited_data_use

boolean

false

Não

Ativa o uso limitado de dados.

data[].user.phone

string

"a1b2c3..."


Telefone do lead com hash SHA-256.

data[].user.wa_id

string

"5531999998888"


Número do WhatsApp do lead.

data[].user.external_id

string

"b2c3d4..."

Não

ID do lead no seu sistema, com hash SHA-256.

data[].user.tt_im_clid

string

"EAAJhb0aKXwB..."


ID de clique do anúncio do TikTok.

data[].properties.im_account_id

string

"5531988887777"


Número do WhatsApp da empresa que recebeu a conversa.

data[].properties.value

number

1500.0

Não

Valor do evento. Use apenas em eventos que aceitam valor.

data[].properties.currency

string

"BRL"

Com value

Moeda do valor, no padrão ISO 4217.

data[].properties.order_id

string

"ORD-2026-000123"

Não

ID do pedido no seu sistema.

data[].properties.description

string

"Pagamento do pedido"

Não

Descrição livre do evento.

Eventos aceitos

Evento

Quando usar

Métrica no relatório do TikTok

Aceita value

Lead

O lead deixou dados de contato, como telefone ou e-mail.

form

Sim

PlaceAnOrder

O lead fez um pedido.

purchase

Sim

CompletePayment

O pagamento foi concluído.

complete_payment

Sim

AddPaymentInfo

O lead informou os dados de pagamento.

add_payment_info

Não

Importante
Para o evento aparecer como purchase no relatório do TikTok, envie PlaceAnOrder. Não existe um evento Purchase.

Exemplo

JSON
{
  "event_source": "crm",
  "event_source_id": "7123456789012345678",
  "partner_name": "cvortex",
  "messaging_channel": "whatsapp",
  "assetId": "1234567890",
  "data": [
    {
      "event": "CompletePayment",
      "event_time": 1790380800,
      "event_id": "9f8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
      "limited_data_use": false,
      "user": {
        "phone": "a1b2c3d4e5f60718293a4b5c6d7e8f901a2b3c4d5e6f708192a3b4c5d6e7f809",
        "wa_id": "5531999998888",
        "external_id": "b2c3d4e5f60718293a4b5c6d7e8f901a2b3c4d5e6f708192a3b4c5d6e7f809a1",
        "tt_im_clid": "EAAJhb0aKXwBAxxxxxxxxxxxxxxxxxxxxx"
      },
      "properties": {
        "im_account_id": "5531988887777",
        "value": 1500.0,
        "currency": "BRL",
        "order_id": "ORD-2026-000123",
        "description": "Pagamento do pedido"
      }
    }
  ]
}