ex_wechat v0.1.3 ExWechat

An elixir Wechat api. Functional and clear.

This sdk will read api definition from definition files(lib/ex_wechat/apis), then it will automaticlly add all the function you define in these definition files.

All the methods in definition file are like this:

  //---------------------
  //  access_token
  //---------------------

  @endpoint https://api.weixin.qq.com/cgi-bin

  # this is the doc you set for the function.

  function: function_name
  path: http request path
  http: the method use for request(get or post)
  params: the params needed for make the http request

You also can add your own api definition files. Set the api definition folder in config.exs, then you can use the api you define. For example:

  # config/config.exs
  config :ex_wechat, ExWechat,
    appid: System.get_env("WECHAT_APPID"),
    secret: System.get_env("WECHAT_APPSECRET"),
    token: System.get_env("WECHAT_TOKEN"),
    access_token_cache: "/tmp/access_token"
    api_definition_files: Path.join(__DIR__, "lib/demo/apis")

  # lib/demo/apis/simple_user
  @endpoint https://api.weixin.qq.com/cgi-bin

  # get user list
  function: get_user_list
  path: /user/get
  http: get
  params: access_token

  # web/controller/user_controller.ex
  defmodule Demo.UserController do
    use Demo.Web, :controller
    use ExWechat.Api

    @api [:simple_user] # file name of the api definition file

    def index(conn, _) do
      get_user_list
    end
  end

Normally, when you add:

  use ExWechat.Api

to your module, this module will read all the api definition files, define and import all the medthod you put in api definition file, each method is a get or post http request. All the Http methods use HTTPosion.

  defmodule MenuController do
    use ExWechat.Api

    @api [:menu]

    # post method
    create_menu(post_body, extra_params \\ [])
    # get method
    get_menu(extra_params \\ [])
  end

You can only import the menu api by add:

  @api [:menu]

When use a post method, it is you responsibility to offer the right data(Elixir Map), when post data, it will convert to json by the api.

Summary

Functions

Issues a DELETE request to the given url

Issues a DELETE request to the given url, raising an exception in case of failure

Issues a GET request to the given url

Issues a GET request to the given url, raising an exception in case of failure

get the access_token from wechat server

get media, added_params(media_id)

get all the menu config

get code with ticket

get user info, added_params(openid)

Issues a HEAD request to the given url

Issues a HEAD request to the given url, raising an exception in case of failure

Issues an OPTIONS request to the given url

Issues a OPTIONS request to the given url, raising an exception in case of failure

Issues a PATCH request to the given url

Issues a PATCH request to the given url, raising an exception in case of failure

Issues a POST request to the given url

Issues a POST request to the given url, raising an exception in case of failure

Issues a PUT request to the given url

Issues a PUT request to the given url, raising an exception in case of failure

Issues an HTTP request with the given method to the given url

Issues an HTTP request with the given method to the given url, raising an exception in case of failure

Starts HTTPoison and its dependencies

change the avatar of kf_account, added_params(kf_account)

upload media, needed_params(type)

Types

body()
body() :: binary | {:form, [{atom, any}]} | {:file, binary}
headers()
headers ::
  [{binary, binary}] |
  %{optional(binary) => binary}

Functions

add_kf_account(post_body, added_params \\ [])

add the kf_account

add_other_permanent(post_body, added_params \\ [])

add other permanent image

add_permanent_image(post_body, added_params \\ [])

add permanent image

add_permanent_news(post_body, added_params \\ [])

add forever news

cancel_blacklist(post_body, added_params \\ [])

cancel user in blacklist

create_menu(post_body, added_params \\ [])

create the menu

create_qrcode_ticket(post_body, added_params \\ [])

generate qrcode ticket

create_special_menu(post_body, added_params \\ [])

special menu create

create_user_tag(post_body, added_params \\ [])

create user tag

delete(url, headers \\ [], options \\ [])

Issues a DELETE request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

delete!(url, headers \\ [], options \\ [])

Issues a DELETE request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

delete_kf_account(post_body, added_params \\ [])

delete the kf_account

delete_menu(added_params \\ [])

delete the menu

delete_permanent(post_body, added_params \\ [])

delete permanent resource

delete_special_menu(post_body, added_params \\ [])

delete special menu

delete_user_tag(post_body, added_params \\ [])

get the server ip

get(url, headers \\ [], options \\ [])

Issues a GET request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

get!(url, headers \\ [], options \\ [])

Issues a GET request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

get_access_token(added_params \\ [])

get the access_token from wechat server

get_all_kf_account(added_params \\ [])

get all the kf_account

get_blacklist(post_body, added_params \\ [])

get users in blacklists

get_media(added_params \\ [])

get media, added_params(media_id)

get_media_list(post_body, added_params \\ [])

get media list

get_menu(added_params \\ [])

get the menu

get_menu_conf(added_params \\ [])

get all the menu config

get_permanent(post_body, added_params \\ [])

get permanent resource

get_permanent_resources_count(added_params \\ [])

get permanent resources count

get_qrcode(added_params \\ [])

get code with ticket

get_server_ip(added_params \\ [])

get the server ip

get_short_url(post_body, added_params \\ [])

get the short url

get_tags_on_user(post_body, added_params \\ [])

get user’s tag

get_user_info(added_params \\ [])

get user info, added_params(openid)

get_user_list(added_params \\ [])

get user list

get_user_tag(added_params \\ [])

get user tags

get_users_in_tag(post_body, added_params \\ [])

get uses in tag

get_users_info(post_body, added_params \\ [])

get users info

head(url, headers \\ [], options \\ [])

Issues a HEAD request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

head!(url, headers \\ [], options \\ [])

Issues a HEAD request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

options(url, headers \\ [], options \\ [])

Issues an OPTIONS request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

options!(url, headers \\ [], options \\ [])

Issues a OPTIONS request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

patch(url, body, headers \\ [], options \\ [])

Issues a PATCH request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

patch!(url, body, headers \\ [], options \\ [])

Issues a PATCH request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

post(url, body, headers \\ [], options \\ [])

Issues a POST request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

post!(url, body, headers \\ [], options \\ [])

Issues a POST request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

put(url, body \\ "", headers \\ [], options \\ [])

Issues a PUT request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

put!(url, body \\ "", headers \\ [], options \\ [])

Issues a PUT request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

put_blacklist(post_body, added_params \\ [])

put users in blacklist

request(method, url, body \\ "", headers \\ [], options \\ [])
request(atom, binary, body, headers, Keyword.t) ::
  {:ok, HTTPoison.Response.t | HTTPoison.AsyncResponse.t} |
  {:error, HTTPoison.Error.t}

Issues an HTTP request with the given method to the given url.

This function is usually used indirectly by get/3, post/4, put/4, etc

Args:

  • method - HTTP method as an atom (:get, :head, :post, :put, :delete, etc.)
  • url - target url as a binary string or char list
  • body - request body. See more below
  • headers - HTTP headers as an orddict (e.g., [{"Accept", "application/json"}])
  • options - Keyword list of options

Body:

  • binary, char list or an iolist
  • {:form, [{K, V}, ...]} - send a form url encoded
  • {:file, "/path/to/file"} - send a file

Options:

  • :timeout - timeout to establish a connection, in milliseconds. Default is 8000
  • :recv_timeout - timeout used when receiving a connection. Default is 5000
  • :stream_to - a PID to stream the response to
  • :proxy - a proxy to be used for the request; it can be a regular url or a {Host, Proxy} tuple
  • :proxy_auth - proxy authentication {User, Password} tuple
  • :ssl - SSL options supported by the ssl erlang module
  • :follow_redirect - a boolean that causes redirects to be followed
  • :max_redirect - an integer denoting the maximum number of redirects to follow
  • :params - an enumerable consisting of two-item tuples that will be appended to the url as query string parameters

Timeouts can be an integer or :infinity

This function returns {:ok, response} or {:ok, async_response} if the request is successful, {:error, reason} otherwise.

Examples

request(:post, "https://my.website.com", "{\"foo\": 3}", [{"Accept", "application/json"}])
request!(method, url, body \\ "", headers \\ [], options \\ [])
request!(atom, binary, body, headers, Keyword.t) :: HTTPoison.Response.t

Issues an HTTP request with the given method to the given url, raising an exception in case of failure.

request!/5 works exactly like request/5 but it returns just the response in case of a successful request, raising an exception in case the request fails.

send_custom_message(post_body, added_params \\ [])

send custom message to user

start()

Starts HTTPoison and its dependencies.

tag_at_users(post_body, added_params \\ [])

tag at user

untag_at_users(post_body, added_params \\ [])

untag user

update_kf_account(post_body, added_params \\ [])

edit the kf_account

update_kf_account_avatar(post_body, added_params \\ [])

change the avatar of kf_account, added_params(kf_account)

update_permanent_news(post_body, added_params \\ [])

update permanent news

update_user_remark(post_body, added_params \\ [])

update user remark

update_user_tag(post_body, added_params \\ [])

update user tag

upload_media(post_body, added_params \\ [])

upload media, needed_params(type)