Skip to main content

​
Quando ocorre

Este evento é disparado sempre que a SocialSell recebe uma mensagem de um contato — via WhatsApp, Messenger ou Instagram. É um dos eventos mais frequentes e mais úteis para construir integrações em tempo real.

​
Casos de uso comuns

  • Responder automaticamente com uma mensagem de confirmação ou menu
  • Acionar um fluxo de atendimento em outro sistema
  • Registrar a mensagem em um sistema de tickets (Zendesk, Freshdesk)
  • Notificar o responsável pelo contato quando ele manda mensagem
  • Escalar para atendimento humano se o agente de IA não souber responder
  • Alimentar um sistema de analytics de intenção de compra com o conteúdo das mensagens

​
Payload completo

{
  "id": "evt_01jxe6f7g8h9i0j1k2l3m4n5o",
  "event": "message.received",
  "organization_id": "664a1b2c3d4e5f6789012345",
  "created_at": "2026-06-10T15:45:00.000Z",
  "data": {
    "id": "664i4j5k6l7m8n9o0p1q2r3s",
    "conversation_id": "664g2h3i4j5k6l7m8n9o0p1q",
    "channel": "whatsapp",
    "direction": "inbound",
    "type": "text",
    "content": "Olá, gostaria de saber mais sobre os planos.",
    "media_url": null,
    "media_mime": null,
    "contact": {
      "id": "664f1a2b3c4d5e6f78901234",
      "name": "João Silva",
      "phone": "+5511999999999",
      "whatsapp_jid": "5511999999999@s.whatsapp.net"
    },
    "whatsapp_instance": {
      "id": "664h3i4j5k6l7m8n9o0p1q2r",
      "name": "WhatsApp Principal",
      "phone": "+5511333344445"
    },
    "messenger_page": null,
    "received_at": "2026-06-10T15:45:00.000Z"
  }
}

​
Exemplo com mídia (imagem)

{
  "data": {
    "id": "664j5k6l7m8n9o0p1q2r3s4t",
    "channel": "whatsapp",
    "type": "image",
    "content": "Segue o comprovante de pagamento",
    "media_url": "https://cdn.socialsell.ai/media/664j5k6l7m8n9o0p1q2r3s4t.jpg",
    "media_mime": "image/jpeg",
    "contact": { "id": "...", "name": "Ana Costa" },
    "received_at": "2026-06-10T16:00:00.000Z"
  }
}

​
Referência de campos

CampoTipoDescrição
data.idstringID da mensagem
data.conversation_idstringID da conversa na SocialSell
data.channelstringCanal de origem: whatsapp, messenger, instagram
data.directionstringSempre inbound neste evento
data.typestringTipo da mensagem: text, image, video, audio, document, sticker, location
data.contentstring|nullTexto da mensagem (ou legenda para mídia)
data.media_urlstring|nullURL da mídia, quando aplicável
data.media_mimestring|nullMIME type da mídia (ex: image/jpeg)
data.contactobjectRemetente: {id, name, phone, whatsapp_jid}
data.whatsapp_instanceobject|nullInstância WhatsApp que recebeu, se canal = whatsapp
data.messenger_pageobject|nullPágina Messenger que recebeu, se canal = messenger
data.received_atstringTimestamp de recebimento

​
Exemplo de handler

if (event === 'message.received') {
  const { contact, channel, type, content, conversation_id } = data;

  // Notificar responsável se contato tiver responsável atribuído
  const storedContact = await db.contacts.findById(contact.id);
  if (storedContact?.assignedMemberId) {
    await slack.notify(storedContact.assignedMemberId, {
      text: `💬 Nova mensagem de ${contact.name} via ${channel}: "${content?.substring(0, 100)}"`
    });
  }

  // Criar ticket no Zendesk para mensagens de suporte
  if (content?.toLowerCase().includes('problema') || content?.toLowerCase().includes('erro')) {
    await zendesk.tickets.create({
      subject: `Mensagem de ${contact.name}`,
      description: content,
      requester: { name: contact.name },
      tags: ['socialsell', channel],
      externalId: conversation_id,
    });
  }

  // Responder automaticamente fora do horário comercial
  const hour = new Date().getHours();
  if (hour < 8 || hour >= 18) {
    await socialsellApi.sendMessage({
      contact_id: contact.id,
      channel,
      type: 'text',
      content: 'Recebemos sua mensagem! Nosso horário de atendimento é das 8h às 18h. Retornaremos em breve.',
    });
  }
}