Skip to content

Social Link

WeChat integration

Creating a configuration

Before creating a socialauth configuration you should create a mobile application (known as an Official Account) in the WeChat admin panel. This application will provide details such as app_id and app_secret that will be required.

WeChat uses an OAuth 2 flow to authorize visitors so you will need to provide a redirect URI when creating your WeChat mobile application. Please use the relevant service URL. WeChat will attempt to confirm ownership of this domain and will ask you to upload a text file to the root of the domain. You don't need to do this, instead take a note of the file name and file contents WeChat provides and add them to your XPKit socialauth configuration.

Linking flow for the visitor

Once you have added all the details from the WeChat mobile application into a socialauth configuration your application (deployed within the WeChat mobile app) can send visitors into the social linking flow. XPKit will:

  • show the visitor the WeChat authorization screen so they can confirm your application can access their details
  • save the visitor's details to their XPKit profile
  • redirect the visitor back to your app using a provided application_uri with their XPKit profile_id as a query parameter
  • if there was an error during the linking flow an error_code will be provided instead

WeChat social linking URL

You need to send your visitors to this URL to start the linking flow:

{% service_url %}/api/wechat/authorise/
    ?account_id=[xpkit account ID]
    &auth_type=[snsapi_base|snsapi_userinfo]
    &application_uri=[encoded app URL]
  • If you are unsure what your Account ID (account_id) is you can find it in XPKit Portal.
  • For auth_type:
    • snsapi_base = silent authentication (default). No personal details will be requested and only the visitor's WeChat OpenID will be saved to their XPKit profile
    • snsapi_userinfo = authentication with popup dialog box for visitor
  • Visitors will be redirected back to the application_uri to finish the flow

Error codes

Error code Reason
100 Invalid User-Agent header
101 Invalid service account
102 No code received from WeChat
103 No token received from WeChat
104 Problem saving profile to XPKit
105 Invalid or no XPKit account

Notes on error codes:

  • 100: when the request header User-Agent is not equal to micromessenger. WeChat sets this when your application is run from inside the WeChat app. When testing outside of WeChat ensure you set this yourself
  • 101: the provided application_uri does not match any domain specified in a socialauth configuration
  • 102/103: XPKit couldn't authenticate with WeChat
  • 104: XPKit authenticated but could not update the visitor's profile
  • 105: the provided acount_id is either missing or invalid

XPKit Profile mapping

If auth_type is set to snsapi_userinfo, WeChat will make the following user information available:

  • openid
  • sex
  • city
  • province
  • country
  • nickname
  • headimgurl

These fields are stored in an XPKit profile like so:

{
    "wechat_openid": [""],
    "gender": "Male|Female",
    "address": {
        "city": "",
        "province": "",
        "country": ""
    },
    "social": [
        {
            "type": "wechat",
            "openid": "",
            "nickname": "",
            "headimgurl": ""
        }
    ]
}

Notes on OpenIDs

You'll notice the type of the mapped wechat_openid field is an array of strings. This is because if you create multiple WeChat applications (Offical Accounts), the same user will have a different OpenID per application. XPKit sets this as an array to allow you to later merge profiles if necessary.

To filter profiles by OpenIDs in the Profiles API you can use the in operator:

{% profiles_service_url %}/api/profile/?wechat_openid__in={% openid %}