\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\nHay algunas cosas que hay que hacer bien aqu\u00ed. La cadena firmada es el cuerpo sin procesar, el nonce y la marca de tiempo\u00a0unidos por puntos, en ese orden, y el resumen es base64 en lugar de hexadecimal. Calc\u00falalo sobre los bytes\u00a0sin procesar, no sobre un diccionario reserializado, o nunca coincidir\u00e1. La clave es el secreto que configuraste al\u00a0crear el webhook, y x-sinch-webhook-signature-algorithm<\/code> te indica qu\u00e9 algoritmo se us\u00f3\u00a0(HmacSHA256<\/code> a d\u00eda de hoy).<\/p>\n\n\n\nUna firma v\u00e1lida por s\u00ed sola no indica que la solicitud sea reciente. Cualquiera que capture una devoluci\u00f3n de llamada\u00a0firmada puede enviarla de nuevo y el HMAC se validar\u00e1 de todos modos; para eso est\u00e1n la marca de tiempo y el nonce:\u00a0Sinch describe el nonce como \u00fanico por devoluci\u00f3n de llamada exactamente con este fin. La\u00a0ventana de cinco minutos anterior es mi propia elecci\u00f3n, no un valor documentado, y es la parte f\u00e1cil. Si\u00a0necesitas un procesamiento estricto de una sola vez, guarda en cach\u00e9 los nonces que ya hayas aceptado durante el tiempo que dure esa\u00a0ventana y rechaza las repeticiones. Tambi\u00e9n merece la pena tener un manejo idempotente, porque Sinch realiza reintentos con un\u00a0retroceso exponencial y, de hecho, ver\u00e1s el mismo recibo dos veces de forma leg\u00edtima, pero la idempotencia no es una\u00a0protecci\u00f3n contra la repetici\u00f3n: evita que una devoluci\u00f3n de llamada repetida corrompa tu estado, pero nunca te dir\u00e1 que\u00a0se ha repetido.<\/p>\n\n\n\n
A\u00f1adir RCS<\/h2>\n\n\n\n Como la ruta de env\u00edo ya es independiente del canal, RCS es un tipo de mensaje y una propiedad del canal:<\/p>\n\n\n
\r\n\r\n
Actualiza el recordatorio a una tarjeta enriquecida RCS con el remitente verificado de RockBank, un resumen del pago y un bot\u00f3n de \u201cPagar ahora\u201d que abra nuestra p\u00e1gina de pago alojada. Mant\u00e9n SMS como alternativa para los dispositivos que no sean compatibles con RCS.<\/p><\/div>\r\n <\/div>\r\n\n\n\n
La tarjeta es un card_message<\/code> que incluye una opci\u00f3n url_message<\/code>, la cual se entrega al mismo _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> es un \u00fanico mapa plano, por lo que la clave RCS y el SMS_SENDER<\/code> que necesita la alternativa acaban\u00a0en el mismo diccionario. Esa fusi\u00f3n es la raz\u00f3n por la que _send<\/code> toma las propiedades como argumento en lugar de\u00a0construirlas de forma integrada. RCS_WEBVIEW_MODE<\/code> controla qu\u00e9 parte de la pantalla ocupa la p\u00e1gina de pago cuando\u00a0se abre: FULL<\/code>, HALF<\/code> o TALL<\/code>.<\/p>\n\n\n\nHay dos detalles sobre RCS en los que es f\u00e1cil equivocarse:<\/p>\n\n\n\n
RCS no procesa el pago.<\/strong> El bot\u00f3n de \u201cPagar ahora\u201d es una acci\u00f3n URL. Abre la\u00a0p\u00e1gina de pago alojada en una vista web sobre el hilo, la clientela paga ah\u00ed y el control vuelve a la\u00a0conversaci\u00f3n. Lo que te aporta RCS es el remitente verificado, la tarjeta de marca y una clientela que nunca\u00a0sale de su aplicaci\u00f3n de mensajer\u00eda. El pago se sigue procesando a trav\u00e9s de tu proveedor de pagos.<\/p>\n\n\n\nLos fallos en la alternativa llegan tarde.<\/strong> Cada canal que nombres en channel_priority_order<\/code> tiene que estar\u00a0configurado en la aplicaci\u00f3n o la solicitud se rechazar\u00e1 de plano, lo cual es el caso f\u00e1cil de depurar. El caso\u00a0m\u00e1s dif\u00edcil es el de un canal configurado que luego falla al realizar la entrega: messages:send<\/code> devuelve un 200 y el\u00a0resultado aparece m\u00e1s tarde como una devoluci\u00f3n de llamada MESSAGE_DELIVERY<\/code>, con SWITCHING_CHANNEL<\/code> marcando el punto\u00a0en el que se activ\u00f3 la alternativa. Otro motivo para configurar bien los disparadores de webhooks antes de depender de la\u00a0ruta alternativa.<\/p>\n\n\n\nVoz, verificaci\u00f3n y email<\/h2>\n\n\n\n Cada una de las cuatro partes restantes se resolvi\u00f3 con un prompt.<\/p>\n\n\n\n
Voz.<\/strong> Si el recordatorio no recibe respuesta y el pago sigue pendiente, RockBank llama. Una\u00a0llamada de texto a voz no necesita ning\u00fan servidor de flujos de llamadas, solo un POST a la API de voz:<\/p>\n\n\n \r\n\r\n
A\u00f1ade un recordatorio de voz para los pagos que sigan pendientes dos d\u00edas despu\u00e9s de que se enviara el mensaje. Usa una llamada de texto a voz a trav\u00e9s de la API de voz de Sinch con nuestras credenciales de la aplicaci\u00f3n de voz, y establece el identificador de llamadas en nuestro 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\nF\u00edjate en la diferencia de autenticaci\u00f3n: la voz utiliza una clave y un secreto de aplicaci\u00f3n, no las credenciales\u00a0a nivel de proyecto que emplea la API de conversaci\u00f3n. Producto diferente, esquema de autenticaci\u00f3n diferente, y las Skills\u00a0cubren ambos, as\u00ed que no hubo que explicar ninguno de los dos en el prompt.<\/p>\n\n\n\n
Para una llamada telef\u00f3nica, destination<\/code> es {\"type\": \"number\", \"endpoint\": \"+46...\"}<\/code> en E.164, y la\u00a0respuesta te devuelve un callId<\/code>. La referencia de la API indica que el par\u00e1metro cli<\/code> es opcional, pero config\u00faralo de todos modos con un\u00a0n\u00famero verificado o uno asignado desde tu panel de control: sin un identificador de llamadas \u00fatil, puedes recibir un ID de llamada\u00a0de una llamada que en realidad nunca lleg\u00f3 al tel\u00e9fono.<\/p>\n\n\n\nVerificaci\u00f3n.<\/strong> Un c\u00f3digo de acceso de un solo uso antes de que la p\u00e1gina de pago acepte nada:<\/p>\n\n\n \r\n\r\n
Antes de que la p\u00e1gina de pago acepte nada, verifica al cliente con un c\u00f3digo de acceso de un solo uso por SMS a trav\u00e9s de la API de verificaci\u00f3n de Sinch. Exp\u00f3n el m\u00e9todo para que podamos cambiarlo en cada solicitud.<\/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> es un tercer conjunto de credenciales: la verificaci\u00f3n se autentica con la clave y\u00a0el secreto de su propia aplicaci\u00f3n en el panel de control, as\u00ed que no son ni las claves a nivel de proyecto que usa la API de conversaci\u00f3n\u00a0ni las de la aplicaci\u00f3n de voz.<\/p>\n\n\n\nstart<\/code> devuelve un id<\/code>, y frente a ese ID es como presentas el c\u00f3digo en el informe. Los valores del m\u00e9todo son la parte que\u00a0merece la pena conocer: sms<\/code> para un c\u00f3digo de acceso por mensaje, callout<\/code> para uno que se lee en una llamada de tel\u00e9fono, adem\u00e1s de\u00a0flashcall<\/code>, seamless<\/code> y whatsapp<\/code>. El cuerpo del informe utiliza el mismo m\u00e9todo como clave, por lo que ser\u00e1\u00a0{\"method\": \"sms\", \"sms\": {\"code\": \"1234\"}}<\/code> para el mensaje y\u00a0{\"method\": \"callout\", \"callout\": {\"code\": \"1234\"}}<\/code> para la llamada.<\/p>\n\n\n\nLas verificaciones caducan al cabo de unos minutos, as\u00ed que debes tratar un error 400 en el informe como \u201ciniciar una nueva\u201d en lugar de\u00a0como un intento fallido. Cambiar a un cliente a