API Local da Plataforma do WhatsApp Business

Notificações de status e preço

O cliente da WhatsApp Business API envia notificações sobre o status da mensagem entre você e seus usuários. Essas notificações são enviadas por meio do objeto statuses.

Atualizações de status

Você receberá uma notificação sobre o status de cada mensagem que a sua empresa enviar. Na tabela abaixo, clique na seta na coluna da esquerda para ver o equivalente do app WhatsApp para cada status, se estiver disponível.

NomeDescrição

deleted

A mensagem enviada foi excluída pelo usuário. Depois de receber essa notificação, você precisa garantir que a mensagem seja excluída do seu sistema caso ela tenha sido baixada do servidor.

Equivalente do app WhatsApp

A mensagem é substituída no WhatsApp para dispositivos móveis por uma nota em que se lê "Esta mensagem foi excluída".

delivered

Uma mensagem enviada pela sua empresa foi entregue ao dispositivo do usuário.

Equivalente do app WhatsApp

Duas marcas de seleção

failed

O envio de uma mensagem da sua empresa falhou. O motivo da falha será incluído no retorno de chamada. Verifique a documentação sobre mensagens de erro para obter ajuda com a depuração:

Equivalente do app WhatsApp

Triângulo de erro vermelho

read

Uma mensagem enviada pela sua empresa foi lida pelo usuário. As notificações de read estarão disponíveis somente para usuários que habilitaram os recibos de leitura. Para usuários que não tiverem essa opção habilitada, você receberá somente a notificação de delivered .

Equivalente do app WhatsApp

Duas marcas de seleção azuis

sent

Uma mensagem enviada pela empresa está em trânsito nos nossos sistemas.


Usuários da API Local: para receber notificações de mensagens sent defina sent_status como true nas configurações do app. A notificação de status sent é desabilitada por padrão.

Equivalente do app WhatsApp

Uma marca de seleção

warning

Uma mensagem enviada pela empresa contém um item de catálogo que não está disponível ou não existe.

A ordem dessas notificações no seu app pode não refletir o momento real do status da mensagem. Se necessário, veja o registro de data e hora para determinar o momento.

Para que um status seja read, ele deve ter sido delivered. Em alguns cenários, por exemplo, quando um usuário estiver na tela de bate-papo e uma mensagem for recebida, ela será delivered e read quase simultaneamente. Nesse ou em outros cenários semelhantes, a notificação delivered não será enviada de volta, pois quando uma mensagem é lida, fica implícito que ela também foi enviada. O motivo para esse comportamento é a otimização interna.

Atualizações de preço

Desde 1º de fevereiro de 2022, o objeto statuses nas suas notificações de saída inclui dois novos objetos aninhados: conversation e pricing. Os componentes do objeto de conversa e preços mudarão de acordo com o local de início da conversa. As conversas podem ser iniciadas pelo usuário ou pela empresa, como também podem ter um ponto de entrada livre. Veja mais informações abaixo:

Exemplos

Nos seguintes exemplos, o recipient_id pode ser um campo group_id. Depende se a mensagem foi enviada para uma pessoa ou um grupo.

Status: Mensagem enviada

O webhook a seguir será recebido quando uma empresa enviar uma mensagem como parte de uma conversa iniciada pelo usuário (caso não tenha sido originada em um ponto de entrada livre):

{
   "statuses": [{
     "id": "ID",
     "recipient_id": "WHATSAPP_ID",
     "status": "sent",
     "timestamp": "TIMESTAMP",
     "type": "message",
     "message": {         
        "recipient_id":"WHATSAPP_ID"   
     },
     "conversation": {
       "id": "CONVERSATION_ID",
       "expiration_timestamp": TIMESTAMP,
       "origin": {
         "type": "user_initiated"
       }
      },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "user_initiated"
    }
   }]
}

O webhook a seguir será recebido quando uma empresa enviar uma mensagem como parte de uma conversa iniciada pelo usuário para uma mensagem de mídia(caso não tenha sido originada em um ponto de entrada livre):

{
   "statuses": [{
     "id": "ID",
     "recipient_id": "WHATSAPP_ID",
     "status": "sent",
     "timestamp": "TIMESTAMP",
     "type": "message",
     "message": {   
       "media_id": "98d14c8e-0310-4061-8f99-2d148274c286",
       "recipient_id":"WHATSAPP_ID"  
     },
     "conversation": {
       "id": "CONVERSATION_ID",
       "expiration_timestamp": TIMESTAMP,
       "origin": {
         "type": "user_initiated"
       }
      },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "user_initiated"
    }
   }]
}

O webhook a seguir será recebido quando uma empresa enviar uma mensagem como parte de uma conversa iniciada pela empresa:

{
  "statuses": [{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "sent",
    "timestamp": "TIMESTAMP",
    "type": "message",         
    "message": {
        "recipient_id":"WHATSAPP_ID" 
    },
    "conversation": {
      "id": "CONVERSATION_ID",
      "expiration_timestamp": TIMESTAMP,
      "origin": {
         "type": "business_initiated"
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "business_initiated"
    }
   }]
}

O webhook a seguir será recebido quando uma empresa enviar uma mensagem em resposta a uma conversa iniciada pelo usuário que tenha sido originada em pontos de entrada livres:

{
  "statuses": [{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "sent",
    "timestamp": "TIMESTAMP",
    "type": "message",
    "message": {
        "recipient_id":"WHATSAPP_ID"   
    },
    "conversation": {
      "id": "CONVERSATION_ID",
      "expiration_timestamp": TIMESTAMP,
      "origin": {
         "type": "referral_conversion",
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": false,
      "category": "referral_conversion"
    }
   }]
}

Status: Mensagem entregue

O webhook a seguir será recebido quando a mensagem de uma empresa for entregue como parte de uma conversa iniciada pelo usuário (caso não tenha sido originada em um ponto de entrada livre):

{
  "statuses": [{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "delivered",
    "timestamp": "TIMESTAMP",
    "type": "message",
    "message": {
        "recipient_id":"WHATSAPP_ID" 
      },
    "conversation": {
      "id": "CONVERSATION_ID",
      "origin": {
         "type": "user_initiated"
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "user_initiated"
    }
  }]
}

O webhook a seguir será recebido quando a mensagem de uma empresa for entregue como parte de uma conversa iniciada pela empresa:

{
  "statuses": [{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "delivered",
    "timestamp": "TIMESTAMP",
    "type": "message",
    "message": {
        "recipient_id": "WHATSAPP_ID" 
    },
    "conversation": {
      "id": "CONVERSATION_ID",
      "origin": {
         "type": "business_initiated"
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "business_initiated"
    }
  }]
}

O webhook a seguir será recebido quando a mensagem de uma empresa for entregue como parte de uma conversa iniciada pelo usuário que tenha sido originada em um ponto de entrada livre:

{
  "statuses": [{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "delivered",
    "timestamp": "TIMESTAMP",
    "type": "message",  
    "message": {
        "recipient_id": "WHATSAPP_ID" 
    },
    "conversation": {
      "id": "CONVERSATION_ID",
      "origin": {
         "type": "referral_conversion",
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": false,
      "category": "referral_conversion"
    }
  }]
}

Status: Mensagem lida

Confira um retorno de chamada padrão para uma mensagem lida:

{
  "statuses":[{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "read",
    "timestamp": "TIMESTAMP",
    "type": "message",  
    "message": {
        "recipient_id": "WHATSAPP_ID" 
    }
  }]
}

Status: Falha na mensagem

Código de erro 470

{
  "statuses": [{
    "errors": [{
      "code": 470,
      "title": "Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid HSM notification or reconsider." 
    }],
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "failed",
    "timestamp": "TIMESTAMP"
  }]
}

Código de erro 480

{
  "statuses": [{
      "errors": [{
          "code": 480,
          "title": "Failed to send message since we detect an identity change of the contact"
      }],
      "id": "ID",
      "recipient_id": "WHATSAPP_ID",
      "status": "failed",
      "timestamp": "TIMESTAMP"
   }]
}

A subseção da conversa não é incluída no retorno de chamada, no caso de falha da mensagem. Nesse caso, não haverá cobrança nem ativação da conversa.

Status: Mensagem excluída

Confira um retorno de chamada padrão para uma mensagem excluída:

{
  "statuses": [{
        "id": "ID",
        "recipient_id": "WHATSAPP_ID",
        "status": "deleted",
        "timestamp": "TIMESTAMP",
        "type": "message",
        "message": {
           "recipient_id": "WHATSAPP_ID" 
      }
    }]
}

A subseção da conversa não é incluída no retorno de chamada, caso a mensagem tenha sido excluída. Nesse caso, não haverá cobrança nem ativação da conversa.

Todos os possíveis status de mensagem

Consulte Messages para obter essa informação.

Perguntas frequentes

Yes, there is a specific scenario where you can get pricing information on your webhook alert for read messages. For each sent message, there can be 3 scenarios:

ScenarioWhen it Happens
You get a webhook alert when the message is delivered (including pricing information) and another webhook alert when the message is read (not including pricing information).This is the most common scenario.
You get a webhook alert when the message is delivered (including pricing information). You do not get a webhook alert that the message has been read. Common when a customer has turned off the feature that lets people know they have read a message.
You get a webhook alert when the message is read (including pricing information). You do not get a webhook alert that the message has been delivered. Only triggered when the user is already reading the thread with the business when the message comes in.
Link permanente