{"openapi":"3.1.0","info":{"title":"WhatsUsernames.link Public API","version":"1.0.0","description":"Free, keyless API for generating WhatsApp links and QR codes from usernames or phone numbers. Rate limited per IP: 60 req/min (JSON endpoints), 20 req/min (/qr). All responses include CORS headers. Note: wa.me/<username> links are in a phased WhatsApp rollout and may not resolve yet — see /llms.txt for current status."},"servers":[{"url":"https://whatsusernames.link"}],"paths":{"/api/v1/username-link":{"get":{"summary":"Generate a WhatsApp link and short link from a username","parameters":[{"name":"username","in":"query","required":true,"description":"WhatsApp username (3-35 chars, lowercase letters, digits, dots, underscores).","schema":{"type":"string"}},{"name":"key","in":"query","required":false,"description":"Optional WhatsApp Username Key (4-8 letters/numbers).","schema":{"type":"string"}},{"name":"text","in":"query","required":false,"description":"Optional prefilled message.","schema":{"type":"string"}}],"responses":{"200":{"description":"Generated links","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsernameLink"},"example":{"username":"joao.silva","key":"AB12","link":"https://wa.me/joao.silva?text=hello","shortLink":"https://whatsusernames.link/joao.silva","notice":"As of 2026-07-04, wa.me/<username> links do not yet open a chat for most accounts..."}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (60/min JSON, 20/min QR, per IP). Includes Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/phone-link":{"get":{"summary":"Generate a WhatsApp click-to-chat link from a phone number","parameters":[{"name":"phone","in":"query","required":true,"description":"Full international number including country code. Symbols/spaces are stripped.","schema":{"type":"string"}},{"name":"text","in":"query","required":false,"description":"Optional prefilled message.","schema":{"type":"string"}}],"responses":{"200":{"description":"Generated link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneLink"},"example":{"phone":"351912345678","link":"https://wa.me/351912345678"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (60/min JSON, 20/min QR, per IP). Includes Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/validate/username":{"get":{"summary":"Validate a WhatsApp username","parameters":[{"name":"username","in":"query","required":true,"description":"Username to validate.","schema":{"type":"string"}}],"responses":{"200":{"description":"Validation verdict (always 200 for a well-formed request)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Validation"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (60/min JSON, 20/min QR, per IP). Includes Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/validate/key":{"get":{"summary":"Validate a WhatsApp Username Key","parameters":[{"name":"key","in":"query","required":true,"description":"Key to validate (4-8 letters/numbers).","schema":{"type":"string"}}],"responses":{"200":{"description":"Validation verdict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Validation"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (60/min JSON, 20/min QR, per IP). Includes Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/validate/phone":{"get":{"summary":"Validate an international phone number for WhatsApp links","parameters":[{"name":"phone","in":"query","required":true,"description":"Phone number to validate.","schema":{"type":"string"}}],"responses":{"200":{"description":"Validation verdict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Validation"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (60/min JSON, 20/min QR, per IP). Includes Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/qr":{"get":{"summary":"Generate a QR code image for a WhatsApp link","parameters":[{"name":"username","in":"query","required":false,"description":"WhatsApp username. Provide exactly one of username or phone.","schema":{"type":"string"}},{"name":"phone","in":"query","required":false,"description":"Phone number. Provide exactly one of username or phone.","schema":{"type":"string"}},{"name":"text","in":"query","required":false,"description":"Optional prefilled message.","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"png (default) or svg.","schema":{"type":"string","enum":["png","svg"]}},{"name":"size","in":"query","required":false,"description":"PNG width in pixels, 128-1024, default 512.","schema":{"type":"integer","minimum":128,"maximum":1024}},{"name":"color","in":"query","required":false,"description":"Foreground hex without #, default 000000.","schema":{"type":"string"}},{"name":"bg","in":"query","required":false,"description":"Background hex without #, or \"transparent\". Default ffffff.","schema":{"type":"string"}}],"responses":{"200":{"description":"QR image","content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/svg+xml":{"schema":{"type":"string"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (60/min JSON, 20/min QR, per IP). Includes Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/business/bsuid/validate":{"post":{"summary":"Validate a WhatsApp Business-Scoped User ID (BSUID) format","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BsuidValidateInput"},"example":{"bsuid":"US.13491208655302741918"}}}},"responses":{"200":{"description":"Validation verdict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BsuidValidation"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (60/min JSON, 20/min QR, per IP). Includes Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/business/bsuid/parse":{"post":{"summary":"Parse a BSUID into its country code, id, and parent-account flag","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BsuidValidateInput"},"example":{"bsuid":"US.ENT.11815799212886844830"}}}},"responses":{"200":{"description":"Parsed BSUID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BsuidParse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (60/min JSON, 20/min QR, per IP). Includes Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/business/username/validate":{"post":{"summary":"Validate a WhatsApp Business Platform username","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsernameValidateInput"},"example":{"username":"joao.silva"}}}},"responses":{"200":{"description":"Validation verdict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessUsernameValidation"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (60/min JSON, 20/min QR, per IP). Includes Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/business/contact/resolve":{"post":{"summary":"Resolve a contact from exactly one of bsuid, phone, or username","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactResolveInput"},"example":{"username":"joao.silva"}}}},"responses":{"200":{"description":"Unified contact shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolvedContact"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (60/min JSON, 20/min QR, per IP). Includes Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/business/webhook/normalize":{"post":{"summary":"Normalize a raw WhatsApp Cloud API webhook payload","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Normalized webhook events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NormalizedWebhook"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (60/min JSON, 20/min QR, per IP). Includes Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/openapi.json":{"get":{"summary":"This document","responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Validation":{"type":"object","properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"required":["valid","errors"]},"UsernameLink":{"type":"object","properties":{"username":{"type":"string"},"key":{"type":"string"},"link":{"type":"string"},"shortLink":{"type":"string"},"notice":{"type":"string"}},"required":["username","link","shortLink","notice"]},"PhoneLink":{"type":"object","properties":{"phone":{"type":"string"},"link":{"type":"string"}},"required":["phone","link"]},"BsuidValidateInput":{"type":"object","properties":{"bsuid":{"type":"string"}},"required":["bsuid"]},"BsuidValidation":{"type":"object","properties":{"valid":{"type":"boolean"},"isParent":{"type":"boolean"}},"required":["valid","isParent"]},"BsuidParse":{"type":"object","properties":{"countryCode":{"type":"string"},"id":{"type":"string"},"isParent":{"type":"boolean"}},"required":["countryCode","id","isParent"]},"UsernameValidateInput":{"type":"object","properties":{"username":{"type":"string"}},"required":["username"]},"BusinessUsernameValidation":{"type":"object","properties":{"valid":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"}}},"required":["valid","reasons"]},"ContactResolveInput":{"type":"object","properties":{"bsuid":{"type":"string"},"phone":{"type":"string"},"username":{"type":"string"}},"description":"Provide exactly one of bsuid, phone, or username."},"ResolvedContact":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["bsuid","phone","username"]},"username":{"type":["string","null"]},"phone":{"type":["string","null"]},"bsuid":{"type":["string","null"]},"displayName":{"type":"null"},"phoneKnown":{"type":"boolean"},"bsuidKnown":{"type":"boolean"}},"required":["id","type","username","phone","bsuid","displayName","phoneKnown","bsuidKnown"]},"NormalizedWebhook":{"type":"object","properties":{"provider":{"type":"string","enum":["meta_cloud_api"]},"events":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["message","status"]},"bsuid":{"type":["string","null"]},"phone":{"type":["string","null"]},"username":{"type":["string","null"]},"displayName":{"type":["string","null"]},"raw":{}}}}},"required":["provider","events"]}}}}