VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp: configuração

Mensagem de boas-vindas

Lê e grava a mensagem automática que a loja envia quando um cliente cumprimenta o WhatsApp, com até 3 botões.

A boas-vindas é a primeira mensagem que o cliente vê. Ela sai quando o cliente manda apenas uma saudação e a regra de trigger permite. Existem dois textos: um para quem a plataforma reconhece pelo número (pode usar o nome) e outro para visitantes. Os botões levam o cliente direto para comprar, ver pedidos, falar com uma pessoa ou seguir uma instrução sua.

Ler a boas-vindas

GET/api/v1/vendor/whatsapp-confluence/welcomeSeller

Retorna a boas-vindas e o que o editor precisa

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/whatsapp-confluence/welcome" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Boas-vindas
json
{
  "config": {
    "enabled": true,
    "message_known": "Olá, {nome}! Seu número foi reconhecido e você já está logado na *{loja}*. Como posso te ajudar hoje?",
    "message_guest": "Olá! Seja bem-vindo(a) à *{loja}*! Como posso te ajudar hoje?",
    "trigger": "inactivity",
    "inactivity_hours": 24,
    "after_exit": true,
    "buttons": [
      {
        "label": "Quero comprar",
        "action": "comprar"
      },
      {
        "label": "Meus pedidos",
        "action": "pedidos"
      },
      {
        "label": "Ofertas da semana",
        "action": "custom",
        "text": "Mostre as ofertas da semana e pergunte a categoria preferida do cliente."
      }
    ],
    "search_help": "Explique que o cliente pode digitar o nome do produto e ofereça o botão da loja."
  },
  "defaults": {
    "enabled": true,
    "message_known": "Olá, {nome}! Seu número foi reconhecido e você já está logado na *{loja}*. Como posso te ajudar hoje?",
    "message_guest": "Olá! Seja bem-vindo(a) à *{loja}*! Como posso te ajudar hoje?",
    "trigger": "inactivity",
    "inactivity_hours": 24,
    "after_exit": true,
    "buttons": [
      {
        "label": "Quero comprar",
        "action": "comprar"
      },
      {
        "label": "Meus pedidos",
        "action": "pedidos"
      },
      {
        "label": "Ofertas da semana",
        "action": "custom",
        "text": "Mostre as ofertas da semana e pergunte a categoria preferida do cliente."
      }
    ],
    "search_help": "Explique que o cliente pode digitar o nome do produto e ofereça o botão da loja."
  },
  "button_defaults": {
    "comprar": "Quero comprar",
    "pedidos": "Meus pedidos"
  },
  "store_name": "Loja Exemplo",
  "search": {
    "audio": false,
    "image": false
  },
  "actions": {
    "comprar": true,
    "promocoes": true,
    "revender": true,
    "pedidos": true,
    "atendente": true,
    "custom": true
  },
  "limits": {
    "body": 1024,
    "buttons": 3,
    "label": 20
  }
}

Campos da resposta

configobject

A boas-vindas salva (ou o padrão, se a loja nunca salvou).

enabledboolean
Liga ou desliga a mensagem. Padrão ligado.
message_knownstring
Texto para quem o número reconhece como cliente cadastrado. Aceita {nome} e {loja}.
message_gueststring
Texto para quem ainda não é reconhecido. Aceita {loja}.
triggerstring
first_contactinactivity
Quando enviar: first_contact só na primeira conversa do telefone; inactivity na primeira conversa e de novo após inactivity_hours sem contato.
inactivity_hoursinteger
Horas de silêncio para uma nova boas-vindas (1 a 720).
after_exitboolean
Quando true, se o cliente sair da conversa a boas-vindas volta na próxima saudação.
buttonsarray

Até 3 botões de resposta rápida.

labelstring
Título do botão, até 20 caracteres, sem repetir outro botão (maiúsculas não contam).
actionstring
comprarpromocoesrevenderpedidosatendentecustom
O que o botão faz.
textstring
Instrução da loja para o assistente quando o cliente toca no botão, até 1024 caracteres. Obrigatória para custom.
search_helpstring
Orientação da loja sobre como ajudar o cliente a buscar produtos, até 1024 caracteres.
defaultsobject
O mesmo formato de config, com os valores de fábrica do segmento da loja. Use para um botão "restaurar padrão".
button_defaultsobject
Título padrão de cada ação (comprar, promocoes, revender, pedidos, atendente, custom).
store_namestring
Nome da loja usado no lugar de {loja}.
searchobject
audio e image (boolean): se a loja aceita busca por áudio e por foto agora.
actionsobject
Mapa ação: boolean. false indica que a ação não funciona agora (por exemplo atendente sem atendimento humano habilitado).
limitsobject
Limites da Meta: buttons 3, label 20, body 1024.

Erros

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não é um seller, ou o seller ainda está em análise de cadastro.{"error":"vendor_pending_review"}

Gravar a boas-vindas

Envie o objeto completo, com os mesmos campos de config. Campos que faltam não recebem padrão: trigger ausente é recusado e inactivity_hours ausente conta como 0 e também é recusado. A resposta é a mesma da leitura, já com o que foi salvo.

PUT/api/v1/vendor/whatsapp-confluence/welcomeSeller

Valida e grava a boas-vindas

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.
Content-Typestringobrigatório
application/json.

Corpo da requisição

enabledbooleanobrigatório
Liga ou desliga.
message_knownstringobrigatório
Texto para cliente reconhecido, 1 a 1024 caracteres. Obrigatório.
message_gueststringobrigatório
Texto para visitante, 1 a 1024 caracteres. Obrigatório.
triggerstringobrigatório
first_contactinactivity
Quando enviar.
inactivity_hoursintegerobrigatório
1 a 720.
after_exitboolean
Reenviar depois que o cliente sai da conversa. Omitido vale false.
buttonsarray
Até 3 botões. Cada um com label (até 20 caracteres, único), action (comprar, promocoes, revender, pedidos, atendente, custom) e text (obrigatório em custom).
search_helpstring
Até 1024 caracteres.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/vendor/whatsapp-confluence/welcome" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "message_known": "Olá, {nome}! Seu número foi reconhecido e você já está logado na *{loja}*. Como posso te ajudar hoje?",
  "message_guest": "Olá! Seja bem-vindo(a) à *{loja}*! Como posso te ajudar hoje?",
  "trigger": "inactivity",
  "inactivity_hours": 24,
  "after_exit": true,
  "buttons": [
    {
      "label": "Quero comprar",
      "action": "comprar"
    },
    {
      "label": "Meus pedidos",
      "action": "pedidos"
    },
    {
      "label": "Ofertas da semana",
      "action": "custom",
      "text": "Mostre as ofertas da semana e pergunte a categoria preferida do cliente."
    }
  ],
  "search_help": "Explique que o cliente pode digitar o nome do produto e ofereça o botão da loja."
}'

Resposta

200Boas-vindas salva
json
{
  "config": {
    "enabled": true,
    "message_known": "Olá, {nome}! Seu número foi reconhecido e você já está logado na *{loja}*. Como posso te ajudar hoje?",
    "message_guest": "Olá! Seja bem-vindo(a) à *{loja}*! Como posso te ajudar hoje?",
    "trigger": "inactivity",
    "inactivity_hours": 24,
    "after_exit": true,
    "buttons": [
      {
        "label": "Quero comprar",
        "action": "comprar"
      },
      {
        "label": "Meus pedidos",
        "action": "pedidos"
      },
      {
        "label": "Ofertas da semana",
        "action": "custom",
        "text": "Mostre as ofertas da semana e pergunte a categoria preferida do cliente."
      }
    ],
    "search_help": "Explique que o cliente pode digitar o nome do produto e ofereça o botão da loja."
  },
  "defaults": {
    "enabled": true,
    "message_known": "Olá, {nome}! Seu número foi reconhecido e você já está logado na *{loja}*. Como posso te ajudar hoje?",
    "message_guest": "Olá! Seja bem-vindo(a) à *{loja}*! Como posso te ajudar hoje?",
    "trigger": "inactivity",
    "inactivity_hours": 24,
    "after_exit": true,
    "buttons": [
      {
        "label": "Quero comprar",
        "action": "comprar"
      },
      {
        "label": "Meus pedidos",
        "action": "pedidos"
      },
      {
        "label": "Ofertas da semana",
        "action": "custom",
        "text": "Mostre as ofertas da semana e pergunte a categoria preferida do cliente."
      }
    ],
    "search_help": "Explique que o cliente pode digitar o nome do produto e ofereça o botão da loja."
  },
  "button_defaults": {
    "comprar": "Quero comprar",
    "pedidos": "Meus pedidos"
  },
  "store_name": "Loja Exemplo",
  "search": {
    "audio": false,
    "image": false
  },
  "actions": {
    "comprar": true,
    "promocoes": true,
    "revender": true,
    "pedidos": true,
    "atendente": true,
    "custom": true
  },
  "limits": {
    "body": 1024,
    "buttons": 3,
    "label": 20
  }
}

Campos da resposta

configobject

A boas-vindas salva (ou o padrão, se a loja nunca salvou).

enabledboolean
Liga ou desliga a mensagem. Padrão ligado.
message_knownstring
Texto para quem o número reconhece como cliente cadastrado. Aceita {nome} e {loja}.
message_gueststring
Texto para quem ainda não é reconhecido. Aceita {loja}.
triggerstring
first_contactinactivity
Quando enviar: first_contact só na primeira conversa do telefone; inactivity na primeira conversa e de novo após inactivity_hours sem contato.
inactivity_hoursinteger
Horas de silêncio para uma nova boas-vindas (1 a 720).
after_exitboolean
Quando true, se o cliente sair da conversa a boas-vindas volta na próxima saudação.
buttonsarray

Até 3 botões de resposta rápida.

labelstring
Título do botão, até 20 caracteres, sem repetir outro botão (maiúsculas não contam).
actionstring
comprarpromocoesrevenderpedidosatendentecustom
O que o botão faz.
textstring
Instrução da loja para o assistente quando o cliente toca no botão, até 1024 caracteres. Obrigatória para custom.
search_helpstring
Orientação da loja sobre como ajudar o cliente a buscar produtos, até 1024 caracteres.
defaultsobject
O mesmo formato de config, com os valores de fábrica do segmento da loja. Use para um botão "restaurar padrão".
button_defaultsobject
Título padrão de cada ação (comprar, promocoes, revender, pedidos, atendente, custom).
store_namestring
Nome da loja usado no lugar de {loja}.
searchobject
audio e image (boolean): se a loja aceita busca por áudio e por foto agora.
actionsobject
Mapa ação: boolean. false indica que a ação não funciona agora (por exemplo atendente sem atendimento humano habilitado).
limitsobject
Limites da Meta: buttons 3, label 20, body 1024.

Erros

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403Falta o privilégio vendor_settings ou vendor_manage_whatsapp, ou o WhatsApp da loja não é deste seller.{"error":"store_whatsapp_owner_required"}
400Campo inválido. field diz qual e reason o motivo: required, too_long, invalid, out_of_range, too_many, duplicate.{"error":"invalid_welcome","detail":"buttons.0.label: too_long","field":"buttons.0.label","reason":"too_long"}
400Corpo que não é JSON.{"error":"invalid body"}
Botão de atendente

O botão atendente só funciona se a loja tiver atendimento humano disponível. Confira actions.atendente na leitura: quando for false, o assistente avisa o cliente que não há atendimento humano no momento.

Veja também

  • Termo de consentimento
  • Voz do assistente
  • Visão geral da seção
Anterior
Segmento e perfil de comércio
Próxima
Termo de consentimento
Nesta página
  • Ler a boas-vindas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Gravar a boas-vindas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também