API atual/Referência completa/WhatsApp: conexão

Atalhos de abertura da conversa

Configura os botões de atalho (ice breakers) que aparecem quando o cliente abre a conversa pela primeira vez.

Ice breakers são botões que o WhatsApp mostra ao cliente antes de ele digitar qualquer coisa, por exemplo "Ver catálogo". Cada botão tem um texto e uma ação fixa (catalog, search ou orders): quando o cliente toca, a plataforma executa a ação. A configuração é por seller. Se vendor_id não for informado, vale o seller principal da loja.

Ler a configuração

Devolve a configuração salva e, ao lado, os atalhos padrão da plataforma.

GET/api/v1/admin/whatsapp/ice-breakersAdmin

Lê os atalhos de abertura de um seller

Parâmetros de consulta

vendor_idstring

UUID do seller. Omitido, usa o seller principal da loja.

Exemplo de requisição (Ler a configuração)

bash

curl "$BASE_URL/api/v1/admin/whatsapp/ice-breakers?vendor_id=c0000000-0000-0000-0000-000000000003" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Ler a configuração)

200Configuração

json

{
  "vendor_id": "c0000000-0000-0000-0000-000000000003",
  "settings": {
    "enabled": true,
    "items": [
      {
        "text": "Ver catálogo",
        "action": "catalog"
      },
      {
        "text": "Buscar produto",
        "action": "search"
      },
      {
        "text": "Meus pedidos",
        "action": "orders"
      }
    ],
    "hide_price_guest": false,
    "enable_quote": true,
    "enable_reactions": true
  },
  "defaults": [
    {
      "text": "Ver catálogo",
      "action": "catalog"
    },
    {
      "text": "Buscar produto",
      "action": "search"
    },
    {
      "text": "Meus pedidos",
      "action": "orders"
    }
  ]
}

Campos da resposta

vendor_idstring

UUID do seller a que as configurações se aplicam.

settingsobject

Configuração atual.

enabledboolean

Liga ou desliga os atalhos de abertura.

itemsarray

De 3 a 4 atalhos. Cada item tem text (até 80 caracteres, sem emojis) e action.

hide_price_guestboolean

Esconde preços de quem ainda não fez login.

enable_quoteboolean

Permite pedir orçamento pelo WhatsApp.

enable_reactionsboolean

Permite reagir a mensagens.

defaultsarray

Atalhos padrão da plataforma (só no GET).

Erros (Ler a configuração)

Status	Quando	Corpo
400	Sem `vendor_id` e a loja não tem seller principal.	`{"error":"vendor_id required"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`

Salvar a configuração

Normaliza os itens, grava e envia à Meta. Itens vazios e repetidos são descartados, no máximo 4 ficam, e se sobrarem menos de 3 a plataforma completa com os padrões. action desconhecida vira catalog.

PUT/api/v1/admin/whatsapp/ice-breakersAdmin

Salva os atalhos de abertura e os envia à Meta

Corpo da requisição

vendor_idstring

UUID do seller. Omitido, usa o seller principal.

settingsobjectobrigatório

Configuração a salvar.

enabledboolean

Liga ou desliga.

itemsarray

Atalhos: objetos {text, action} com action em catalog, search ou orders.

hide_price_guestboolean

Esconde preços de visitantes.

enable_quoteboolean

Permite orçamento.

enable_reactionsboolean

Permite reações.

Exemplo de requisição (Salvar a configuração)

bash

curl -X PUT "$BASE_URL/api/v1/admin/whatsapp/ice-breakers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_id": "c0000000-0000-0000-0000-000000000003",
    "settings": {
      "enabled": true,
      "items": [
        {
          "text": "Ver catálogo",
          "action": "catalog"
        },
        {
          "text": "Meus pedidos",
          "action": "orders"
        }
      ],
      "hide_price_guest": false,
      "enable_quote": true,
      "enable_reactions": true
    }
  }'

Resposta (Salvar a configuração)

200Salvo

json

{
  "vendor_id": "c0000000-0000-0000-0000-000000000003",
  "settings": {
    "enabled": true,
    "items": [
      {
        "text": "Ver catálogo",
        "action": "catalog"
      },
      {
        "text": "Buscar produto",
        "action": "search"
      },
      {
        "text": "Meus pedidos",
        "action": "orders"
      }
    ],
    "hide_price_guest": false,
    "enable_quote": true,
    "enable_reactions": true
  }
}

Campos da resposta

settingsobject

Configuração como ficou depois da normalização (note os itens completados).

Erros (Salvar a configuração)

Status	Quando	Corpo
400	Corpo que não é JSON, ou sem `vendor_id` e sem seller principal.	`{"error":"invalid json"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`
502	Os dados foram guardados, mas a Meta recusou o envio. A resposta traz `settings` e o `error` da Meta.	`{"error":"meta conversational_automation HTTP 400: ...","settings":{}}`

Aplicar a todos os sellers

Percorre todos os sellers com número conectado e reenvia a configuração de cada um à Meta. Útil depois de trocar o token ou de migrar números. Sem corpo.

POST/api/v1/admin/whatsapp/ice-breakers/apply-allAdmin

Reenvia os atalhos de todos os sellers à Meta

Exemplo de requisição (Aplicar a todos os sellers)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/ice-breakers/apply-all" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Aplicar a todos os sellers)

200Resultado por seller

json

{
  "results": [
    {
      "vendor_id": "c0000000-0000-0000-0000-000000000003",
      "ok": true
    }
  ],
  "total": 1,
  "ok": 1
}

Campos da resposta

resultsarray

Uma linha por seller, com vendor_id e ok. Em caso de falha a linha traz também o erro.

totalinteger

Quantidade de sellers processados.

okinteger

Quantidade que deu certo.

Erros (Aplicar a todos os sellers)

Status	Quando	Corpo
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`
500	Falha ao listar os sellers.	`{"error":"..."}`

Veja também

API atual/Referência completa/WhatsApp: conexão

Atalhos de abertura da conversa

Configura os botões de atalho (ice breakers) que aparecem quando o cliente abre a conversa pela primeira vez.

Ler a configuração

Devolve a configuração salva e, ao lado, os atalhos padrão da plataforma.

GET/api/v1/admin/whatsapp/ice-breakersAdmin

Lê os atalhos de abertura de um seller

Parâmetros de consulta

vendor_idstring

UUID do seller. Omitido, usa o seller principal da loja.

Exemplo de requisição (Ler a configuração)

bash

curl "$BASE_URL/api/v1/admin/whatsapp/ice-breakers?vendor_id=c0000000-0000-0000-0000-000000000003" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Ler a configuração)

200Configuração

json

{
  "vendor_id": "c0000000-0000-0000-0000-000000000003",
  "settings": {
    "enabled": true,
    "items": [
      {
        "text": "Ver catálogo",
        "action": "catalog"
      },
      {
        "text": "Buscar produto",
        "action": "search"
      },
      {
        "text": "Meus pedidos",
        "action": "orders"
      }
    ],
    "hide_price_guest": false,
    "enable_quote": true,
    "enable_reactions": true
  },
  "defaults": [
    {
      "text": "Ver catálogo",
      "action": "catalog"
    },
    {
      "text": "Buscar produto",
      "action": "search"
    },
    {
      "text": "Meus pedidos",
      "action": "orders"
    }
  ]
}

Campos da resposta

vendor_idstring

UUID do seller a que as configurações se aplicam.

settingsobject

Configuração atual.

enabledboolean

Liga ou desliga os atalhos de abertura.

itemsarray

De 3 a 4 atalhos. Cada item tem text (até 80 caracteres, sem emojis) e action.

hide_price_guestboolean

Esconde preços de quem ainda não fez login.

enable_quoteboolean

Permite pedir orçamento pelo WhatsApp.

enable_reactionsboolean

Permite reagir a mensagens.

defaultsarray

Atalhos padrão da plataforma (só no GET).

Erros (Ler a configuração)

Status	Quando	Corpo
400	Sem `vendor_id` e a loja não tem seller principal.	`{"error":"vendor_id required"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`

Salvar a configuração

PUT/api/v1/admin/whatsapp/ice-breakersAdmin

Salva os atalhos de abertura e os envia à Meta

Corpo da requisição

vendor_idstring

UUID do seller. Omitido, usa o seller principal.

settingsobjectobrigatório

Configuração a salvar.

enabledboolean

Liga ou desliga.

itemsarray

Atalhos: objetos {text, action} com action em catalog, search ou orders.

hide_price_guestboolean

Esconde preços de visitantes.

enable_quoteboolean

Permite orçamento.

enable_reactionsboolean

Permite reações.

Exemplo de requisição (Salvar a configuração)

bash

curl -X PUT "$BASE_URL/api/v1/admin/whatsapp/ice-breakers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_id": "c0000000-0000-0000-0000-000000000003",
    "settings": {
      "enabled": true,
      "items": [
        {
          "text": "Ver catálogo",
          "action": "catalog"
        },
        {
          "text": "Meus pedidos",
          "action": "orders"
        }
      ],
      "hide_price_guest": false,
      "enable_quote": true,
      "enable_reactions": true
    }
  }'

Resposta (Salvar a configuração)

200Salvo

json

{
  "vendor_id": "c0000000-0000-0000-0000-000000000003",
  "settings": {
    "enabled": true,
    "items": [
      {
        "text": "Ver catálogo",
        "action": "catalog"
      },
      {
        "text": "Buscar produto",
        "action": "search"
      },
      {
        "text": "Meus pedidos",
        "action": "orders"
      }
    ],
    "hide_price_guest": false,
    "enable_quote": true,
    "enable_reactions": true
  }
}

Campos da resposta

settingsobject

Configuração como ficou depois da normalização (note os itens completados).

Erros (Salvar a configuração)

Status	Quando	Corpo
400	Corpo que não é JSON, ou sem `vendor_id` e sem seller principal.	`{"error":"invalid json"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`
502	Os dados foram guardados, mas a Meta recusou o envio. A resposta traz `settings` e o `error` da Meta.	`{"error":"meta conversational_automation HTTP 400: ...","settings":{}}`

Aplicar a todos os sellers

Percorre todos os sellers com número conectado e reenvia a configuração de cada um à Meta. Útil depois de trocar o token ou de migrar números. Sem corpo.

POST/api/v1/admin/whatsapp/ice-breakers/apply-allAdmin

Reenvia os atalhos de todos os sellers à Meta

Exemplo de requisição (Aplicar a todos os sellers)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/ice-breakers/apply-all" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Aplicar a todos os sellers)

200Resultado por seller

json

{
  "results": [
    {
      "vendor_id": "c0000000-0000-0000-0000-000000000003",
      "ok": true
    }
  ],
  "total": 1,
  "ok": 1
}

Campos da resposta

resultsarray

Uma linha por seller, com vendor_id e ok. Em caso de falha a linha traz também o erro.

totalinteger

Quantidade de sellers processados.

okinteger

Quantidade que deu certo.

Erros (Aplicar a todos os sellers)

Status	Quando	Corpo
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`
500	Falha ao listar os sellers.	`{"error":"..."}`