\r\n\r\n import base64\r\nimport hashlib\r\nimport hmac\r\nimport time\r\n\r\nMAX_CALLBACK_AGE_SECONDS = 300\r\n\r\n@router.post("\/sinch\/callbacks")\r\nasync def handle_callback(request: Request) -> Response:\r\n raw_body = await request.body()\r\n signature = request.headers.get("x-sinch-webhook-signature", "")\r\n nonce = request.headers.get("x-sinch-webhook-signature-nonce", "")\r\n timestamp = request.headers.get("x-sinch-webhook-signature-timestamp", "")\r\n\r\n try:\r\n age = abs(time.time() - int(timestamp))\r\n except ValueError:\r\n raise HTTPException(status_code=401, detail="Bad timestamp")\r\n if age > MAX_CALLBACK_AGE_SECONDS:\r\n raise HTTPException(status_code=401, detail="Stale callback")\r\n\r\n signed_data = raw_body + b"." + nonce.encode() + b"." + timestamp.encode()\r\n expected = base64.b64encode(\r\n hmac.new(\r\n settings.webhook_secret.encode(), signed_data, hashlib.sha256\r\n ).digest()\r\n ).decode()\r\n if not hmac.compare_digest(expected, signature):\r\n raise HTTPException(status_code=401, detail="Invalid signature")\r\n\r\n payload = json.loads(raw_body)\r\n if "message_delivery_report" in payload:\r\n await record_delivery(payload["message_delivery_report"])\r\n elif "message" in payload:\r\n await record_inbound_message(payload["message"])\r\n return Response(status_code=200)\r\n <\/code>\r\n <\/pre>\r\n <\/div>\r\n <\/div>\r\n <\/div>\r\n <\/div>\r\n\n\n\nVoc\u00ea precisa acertar algumas coisas aqui. A string assinada \u00e9 o corpo bruto, o nonce e o carimbo de data\/hora\u00a0unidos por pontos, nessa ordem, e o hash (digest) \u00e9 em base64 em vez de hex. Calcule isso sobre os bytes\u00a0brutos, e n\u00e3o sobre um dicion\u00e1rio resserializado, caso contr\u00e1rio nunca haver\u00e1 correspond\u00eancia. A chave \u00e9 o segredo que voc\u00ea definiu ao\u00a0criar o webhook, e x-sinch-webhook-signature-algorithm<\/code> informa qual algoritmo foi usado\u00a0(atualmente, HmacSHA256<\/code>).<\/p>\n\n\n\nApenas uma assinatura v\u00e1lida n\u00e3o indica que a solicita\u00e7\u00e3o \u00e9 nova. Qualquer pessoa que capturar um callback\u00a0assinado poder\u00e1 envi\u00e1-lo novamente e o HMAC ainda far\u00e1 a valida\u00e7\u00e3o, e \u00e9 para isso que o carimbo de data\/hora e o nonce\u00a0servem: a Sinch descreve o nonce como \u00fanico por callback exatamente para esse fim. A\u00a0janela de cinco minutos acima \u00e9 uma escolha minha, e n\u00e3o um valor documentado. Al\u00e9m disso, essa \u00e9 a metade barata do processo. Se\u00a0precisar de um rigoroso processamento de uso \u00fanico, armazene em cache os nonces que voc\u00ea j\u00e1 aceitou pela dura\u00e7\u00e3o desse\u00a0intervalo e rejeite repeti\u00e7\u00f5es. Tamb\u00e9m vale a pena contar com o tratamento idempotente, pois a Sinch tenta novamente com\u00a0recuo (backoff) exponencial e voc\u00ea legitimamente ver\u00e1 a mesma confirma\u00e7\u00e3o de entrega duas vezes, mas a idempot\u00eancia n\u00e3o \u00e9 uma\u00a0prote\u00e7\u00e3o contra repeti\u00e7\u00e3o: ela impede que um callback reproduzido corrompa seu estado sem nunca avisar voc\u00ea\u00a0que ele foi repetido.<\/p>\n\n\n\n
Adi\u00e7\u00e3o de RCS<\/h2>\n\n\n\n Com o caminho de envio independente de canal, o RCS \u00e9 um tipo de mensagem e uma propriedade do canal:<\/p>\n\n\n
\r\n\r\n
Fa\u00e7a o upgrade do lembrete para um rich card de RCS com o remetente verificado do RockBank, um resumo do pagamento e um bot\u00e3o \u201cPagar agora\u201d que abra nossa p\u00e1gina de pagamento hospedada. Mantenha o fallback de SMS para os dispositivos que n\u00e3o aceitam RCS.<\/p><\/div>\r\n <\/div>\r\n\n\n\n
O cart\u00e3o \u00e9 uma card_message<\/code> com a escolha url_message<\/code>, entregue para a mesma _send<\/code> de\u00a0antes:<\/p>\n\n\n \r\n
\r\n\r\n \r\n \r\n \r\n \r\n Shell <\/button>\r\n <\/li>\r\n\r\n \r\n \r\n <\/ul>\r\n \r\n\r\n \r\n
\r\n
\r\n
\r\n
\r\n <\/svg>\r\n <\/svg>\r\n <\/button>\r\n <\/div>\r\n \r\n \r\n\r\n async def send_reminder_card( \r\n self, \r\n to: str, \r\n due_date: date, \r\n amount: Decimal, \r\n account_last4: str, \r\n payment_url: str, \r\n ) -> dict[str, Any]: \r\n card: dict[str, Any] = { \r\n "title": f"Payment due {due_date:%d %b}", \r\n "description": f"Amount: ${amount:,.2f}. Account ending {account_last4}.", \r\n "choices": [ \r\n {"url_message": {"title": "Pay now", "url": payment_url}} \r\n ], \r\n } \r\n return await self._send( \r\n to, \r\n {"card_message": card}, \r\n channel_properties={"RCS_WEBVIEW_MODE": "TALL"}, \r\n ) \r\n <\/code>\r\n <\/pre>\r\n <\/div>\r\n <\/div>\r\n <\/div>\r\n <\/div>\r\n\n\n\nchannel_properties<\/code> \u00e9 um \u00fanico flat map. Portanto, a chave RCS e o SMS_SENDER<\/code> de que o fallback precisa acabam\u00a0no mesmo dicion\u00e1rio. Essa fus\u00e3o \u00e9 o motivo pelo qual _send<\/code> usa as propriedades como argumento em vez de\u00a0constru\u00ed-las em linha. RCS_WEBVIEW_MODE<\/code> controla o quanto da tela a p\u00e1gina de pagamento ocupar\u00e1 quando\u00a0abrir: FULL<\/code>, HALF<\/code> ou TALL<\/code>.<\/p>\n\n\n\nDois detalhes sobre o RCS em que \u00e9 f\u00e1cil errar:<\/p>\n\n\n\n
O RCS n\u00e3o processa o pagamento.<\/strong> O bot\u00e3o \u201cPagar agora\u201d \u00e9 uma a\u00e7\u00e3o de URL. Ele abre a sua p\u00e1gina de pagamento\u00a0hospedada em uma visualiza\u00e7\u00e3o web sobre a thread, o cliente paga l\u00e1 e o controle volta para a\u00a0conversa. O que o RCS fornece \u00e9 o remetente verificado, o rich card com identidade de marca, e um cliente que nunca\u00a0sai de seu app de mensagens. O pagamento ainda passa pelo seu provedor de pagamentos.<\/p>\n\n\n\nFalhas de fallback chegam tarde.<\/strong> Cada canal que voc\u00ea nomeia em channel_priority_order<\/code> precisa ser\u00a0configurado no app ou a solicita\u00e7\u00e3o \u00e9 totalmente rejeitada, que \u00e9 o caso f\u00e1cil de depurar. O\u00a0caso mais dif\u00edcil \u00e9 o de um canal configurado que falha na entrega: messages:send<\/code> retorna 200, e o\u00a0resultado aparece depois como um callback de MESSAGE_DELIVERY<\/code>, com SWITCHING_CHANNEL<\/code> marcando o ponto\u00a0em que o fallback entrou em a\u00e7\u00e3o. Esse \u00e9 outro motivo para acertar nos gatilhos de webhook antes de confiar no caminho de\u00a0fallback.<\/p>\n\n\n\nVoz, verifica\u00e7\u00e3o e e-mail<\/h2>\n\n\n\n As quatro pe\u00e7as restantes exigiram um prompt cada.<\/p>\n\n\n\n
Voz.<\/strong> Se o lembrete ficar sem resposta e o pagamento continuar pendente, o RockBank faz uma chamada. Um\u00a0an\u00fancio de texto para fala n\u00e3o precisa de nenhum servidor de fluxo de chamada, s\u00f3 de um POST para a API de voz:<\/p>\n\n\n \r\n\r\n
Adicione um lembrete de voz para os pagamentos que ainda estiverem pendentes dois dias ap\u00f3s o envio da mensagem. Use um an\u00fancio de texto para fala por meio da API de voz da Sinch usando nossas credenciais do aplicativo de voz, e defina o identificador de chamadas com nosso n\u00famero registrado.<\/p><\/div>\r\n <\/div>\r\n\n\n
\r\n
\r\n\r\n \r\n \r\n \r\n \r\n Shell <\/button>\r\n <\/li>\r\n\r\n \r\n \r\n <\/ul>\r\n \r\n\r\n \r\n
\r\n
\r\n
\r\n
\r\n <\/svg>\r\n <\/svg>\r\n <\/button>\r\n <\/div>\r\n \r\n \r\n\r\n async def place_reminder_call(self, to: str, message: str) -> dict[str, Any]:\r\n """Place a text-to-speech reminder call via the Voice API."""\r\n tts: dict[str, Any] = {\r\n "destination": {"type": "number", "endpoint": to},\r\n "cli": self.caller_id,\r\n "locale": "en-US",\r\n "text": message,\r\n }\r\n response = await self.client.post(\r\n "\/calling\/v1\/callouts",\r\n auth=(self.voice_app_key, self.voice_app_secret),\r\n json={"method": "ttsCallout", "ttsCallout": tts},\r\n )\r\n if response.is_error:\r\n raise SinchClientError(\r\n f"Voice callout failed ({response.status_code}): {response.text}"\r\n )\r\n return response.json()\r\n <\/code>\r\n <\/pre>\r\n <\/div>\r\n <\/div>\r\n <\/div>\r\n <\/div>\r\n\n\n\nAten\u00e7\u00e3o \u00e0 diferen\u00e7a de autentica\u00e7\u00e3o: a voz usa uma chave e segredo de aplicativo, e n\u00e3o as credenciais em n\u00edvel de projeto\u00a0que a Conversation API usa. Produto diferente, esquema de autentica\u00e7\u00e3o diferente, e as Skills\u00a0abrangem os dois. Portanto, o prompt n\u00e3o precisou explicar nenhum deles.<\/p>\n\n\n\n
O destination<\/code> de uma chamada telef\u00f4nica \u00e9 {\"type\": \"number\", \"endpoint\": \"+46...\"}<\/code> no formato E.164, e a\u00a0resposta fornece um callId<\/code>. A refer\u00eancia da API lista cli<\/code> como opcional, mas mesmo assim, defina o campo com um n\u00famero\u00a0verificado ou atribu\u00eddo por meio do seu painel: sem um identificador de chamadas utiliz\u00e1vel, voc\u00ea poder\u00e1 receber o ID\u00a0de uma chamada que sequer chegar\u00e1 ao telefone.<\/p>\n\n\n\nVerifica\u00e7\u00e3o.<\/strong> Uma senha de uso \u00fanico antes que a p\u00e1gina de pagamento aceite qualquer coisa:<\/p>\n\n\n \r\n\r\n
Antes da p\u00e1gina de pagamento aceitar qualquer coisa, fa\u00e7a a verifica\u00e7\u00e3o do cliente com uma senha de uso \u00fanico por SMS, pela API de verifica\u00e7\u00e3o da Sinch. Exponha o m\u00e9todo para podermos altern\u00e1-lo de acordo com a solicita\u00e7\u00e3o.<\/p><\/div>\r\n <\/div>\r\n\n\n
\r\n
\r\n\r\n \r\n \r\n \r\n \r\n Shell <\/button>\r\n <\/li>\r\n\r\n \r\n \r\n <\/ul>\r\n \r\n\r\n \r\n
\r\n
\r\n
\r\n
\r\n <\/svg>\r\n <\/svg>\r\n <\/button>\r\n <\/div>\r\n \r\n \r\n\r\n async def start(self, phone: str, method: str = "sms") -> dict[str, Any]:\r\n response = await self.client.post(\r\n "\/verification\/v1\/verifications",\r\n auth=self._verification_auth,\r\n json={"identity": {"type": "number", "endpoint": phone}, "method": method},\r\n )\r\n ...\r\n\r\nasync def verify(self, reference: str, code: str) -> dict[str, Any]:\r\n path = f"\/verification\/v1\/verifications\/id\/{quote(reference, safe='')}"\r\n response = await self.client.put(\r\n path,\r\n auth=self._verification_auth,\r\n json={"method": "sms", "sms": {"code": code}},\r\n )\r\n ...\r\n <\/code>\r\n <\/pre>\r\n <\/div>\r\n <\/div>\r\n <\/div>\r\n <\/div>\r\n\n\n\n_verification_auth<\/code> \u00e9 um terceiro conjunto de credenciais: a verifica\u00e7\u00e3o autentica com a chave e o\u00a0segredo de seu pr\u00f3prio app no painel. Portanto, n\u00e3o se trata das chaves em n\u00edvel de projeto que a Conversation API\u00a0usa, tampouco as chaves do aplicativo de voz.<\/p>\n\n\n\nstart<\/code> retorna um id<\/code>, e \u00e9 nele que voc\u00ea informa o c\u00f3digo. Os valores de m\u00e9todos s\u00e3o a parte que\u00a0vale a pena conhecer: sms<\/code> para a senha via mensagem, callout<\/code> para que ela seja lida em uma chamada de voz, al\u00e9m de\u00a0flashcall<\/code>, seamless<\/code> e whatsapp<\/code>. O corpo do relat\u00f3rio \u00e9 parametrizado pelo mesmo m\u00e9todo, ou seja,\u00a0{\"method\": \"sms\", \"sms\": {\"code\": \"1234\"}}<\/code> para a mensagem e\u00a0{\"method\": \"callout\", \"callout\": {\"code\": \"1234\"}}<\/code> para a chamada.<\/p>\n\n\n\nAs verifica\u00e7\u00f5es expiram em alguns minutos. Sendo assim, encare um erro 400 no relat\u00f3rio como “inicie um novo” em vez de encarar\u00a0como uma tentativa fracassada. A mudan\u00e7a de um cliente para